@arcforgelabs/flow 2026.10.48 → 2026.10.49

package/server/ui/kit.js

@@ -149,10 +149,31 @@ export function sectionTitle(text, help = null) {
   return h('h2', { class: 'fx-set__title' }, text, help ? helpLink(help) : null);
 }
 
-export function notice(text, tone = 'info', title = null) {
+// With `short`, a phone shows only that one line ("Client not in Xero") in
+// place of the title and text.
+export function notice(text, tone = 'info', title = null, { short = null } = {}) {
   return applyPhoneRule(h('div', { class: 'fx-notice', 'data-tone': tone, role: tone === 'danger' ? 'alert' : 'status' },
-    title ? h('strong', {}, title) : null,
-    h('span', {}, text)), 'notice');
+    title ? h('strong', { class: short ? 'fx-notice__long' : null }, title) : null,
+    h('span', { class: short ? 'fx-notice__long' : null }, text),
+    short ? h('span', { class: 'fx-notice__short' }, short) : null), 'notice');
+}
+
+// A table that is a list of small cards on a phone (CardRows card). On a
+// tablet and desk it stays a table. `areas` places each cell on the card
+// (CSS grid-template-areas, one string per line) and `columns` sizes the
+// card's columns. A cell names its place with `data-area` and its column
+// name with `data-label` (shown above it on a phone). Rows drawn later are
+// placed too.
+export function cardRows(table, { areas, columns }) {
+  table.classList.add('fx-cardrows');
+  table.style.setProperty('--fx-cardrows-areas', areas.map((line) => `"${line}"`).join(' '));
+  table.style.setProperty('--fx-cardrows-columns', columns);
+  const place = () => {
+    for (const cell of table.querySelectorAll('td[data-area]')) cell.style.gridArea = cell.dataset.area;
+  };
+  place();
+  if (typeof MutationObserver === 'function') new MutationObserver(place).observe(table, { childList: true, subtree: true });
+  return applyPhoneRule(table, 'cardRows');
 }
 
 // A field that fails a check glows red, like a required field, until the
@@ -220,17 +241,87 @@ export function dialog({ title, body, confirm, tone = 'primary', choices = null
   });
 }
 
-// One setting, laid out the same on every settings screen: a short name, one
-// line of smaller text under it, and the control on the right. Longer help
-// lives behind a link, not here. A wide control (a grid of choices) sits on
-// its own line under the name. `tone: 'danger'` marks a row that needs a person.
-export function settingRow({ label, hint, control, wide = false, tone = null }) {
+// A dialog that picks one row of a long list (Pick card). A search box over
+// the list; `load(q)` answers the rows for its text (once with '' on open, and
+// again as the person types when `remote`; else the rows filter here).
+// `item(row)` draws a row as { value, title, meta, end }. Answers the picked
+// row, or null on Cancel.
+export async function pickOne({ title, intro = null, label, find = 'Find', load, item, empty, confirm, remote = false }) {
+  const search = h('input', { class: 'fx-input', type: 'search', placeholder: find, 'aria-label': find });
+  const list = h('div', { class: 'fx-pick', role: 'radiogroup', 'aria-label': label }, h('div', { class: 'fx-skeleton' }));
+  let rows = [];
+  const draw = (found) => {
+    rows = found.map((row) => {
+      const { value, title: name, meta = null, end = null } = item(row);
+      const element = h('label', { class: 'fx-pick__row' },
+        h('input', { type: 'radio', name: 'pick', value: String(value), required: true }),
+        h('span', { class: 'fx-pick__main' },
+          h('span', { class: 'fx-strong' }, name),
+          meta ? h('span', { class: 'fx-dim' }, meta) : null),
+        end == null ? h('span') : h('span', { class: 'fx-num fx-strong' }, end));
+      element.dataset.find = `${name} ${meta ?? ''}`.toLowerCase();
+      return { row, value: String(value), element };
+    });
+    list.replaceChildren(...(rows.length ? rows.map((r) => r.element) : [h('p', { class: 'fx-dim' }, empty)]));
+  };
+  let asked = 0;
+  const fill = async (q) => {
+    const turn = ++asked;
+    let found;
+    try {
+      found = await load(q);
+    } catch (error) {
+      found = [];
+      toast(error.message, 'danger');
+    }
+    if (turn === asked) draw(found);
+  };
+  let wait = null;
+  search.addEventListener('input', () => {
+    const q = search.value.trim().toLowerCase();
+    if (remote) {
+      clearTimeout(wait);
+      wait = setTimeout(() => fill(q), 250);
+      return;
+    }
+    for (const r of rows) r.element.hidden = Boolean(q) && !r.element.dataset.find.includes(q);
+  });
+  fill('');
+  const picked = await dialog({
+    title,
+    body: applyPhoneRule(h('div', { class: 'fx-pick__body' }, intro ? h('p', { class: 'fx-dim' }, intro) : null, search, list), 'pickOne'),
+    confirm,
+  });
+  clearTimeout(wait);
+  const value = picked?.get('pick');
+  return value ? rows.find((r) => r.value === value)?.row ?? null : null;
+}
+
+// One setting, laid out the same on every settings screen: a short name and
+// the control on the right. `hint` is a short status line under the name
+// ("3 to check"), never an explanation. `help` is the explanation: a ? beside
+// the name says it on hover, and a press shows it under the name (a phone has
+// no hover). A wide control (a grid of choices) sits on its own line under the
+// name. `tone: 'danger'` marks a row that needs a person.
+export function settingRow({ label, hint, help = null, control, wide = false, tone = null }) {
   const target = control?.matches?.('input, select, textarea') ? control : control?.querySelector?.('input:not([type=color]), select, textarea');
   const id = target ? (target.id ||= `fx-set-${++settingRow.next}`) : null;
+  const helpLine = help ? h('p', { class: 'fx-setting__hint fx-setting__help', hidden: true }, help) : null;
+  const helpButton = help ? named(h('button', {
+    class: 'fx-help', type: 'button', 'aria-expanded': 'false',
+    onclick: (event) => {
+      const open = helpLine.hidden;
+      helpLine.hidden = !open;
+      event.currentTarget.setAttribute('aria-expanded', String(open));
+    },
+  }, lucide(h, 'circle-help')), `About ${label}`, help) : null;
   return applyPhoneRule(h('div', { class: `fx-setting${wide ? ' fx-setting--wide' : ''}`, 'data-tone': tone },
     h('div', { class: 'fx-setting__text' },
-      id ? h('label', { class: 'fx-setting__name', for: id }, label) : h('span', { class: 'fx-setting__name' }, label),
-      hint ? h('p', { class: 'fx-setting__hint' }, hint) : null),
+      h('span', { class: 'fx-setting__head' },
+        id ? h('label', { class: 'fx-setting__name', for: id }, label) : h('span', { class: 'fx-setting__name' }, label),
+        helpButton),
+      hint ? h('p', { class: 'fx-setting__hint' }, hint) : null,
+      helpLine),
     h('div', { class: 'fx-setting__control' }, control)), 'settingRow');
 }
 settingRow.next = 0;

package/server/ui/line-mappings.js

@@ -9,14 +9,12 @@
 const money = (cents) => (cents === null || cents === undefined ? '' : `$${(cents / 100).toFixed(2)}`);
 
 export function lineMappingSection(ui) {
-  const { h, flow, toast, notice, me } = ui;
+  const { h, flow, toast, notice, me, settingRow } = ui;
   const disabled = !['owner', 'admin'].includes(me?.person.role);
   const body = h('div', {}, h('div', { class: 'fx-skeleton' }));
   const section = h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, 'Price codes'), body);
 
-  const row = (name, hint, control) => h('div', { class: 'fx-set__row' },
-    h('div', { class: 'fx-set__text' }, h('span', { class: 'fx-set__name' }, name), h('span', { class: 'fx-set__hint' }, hint)),
-    h('div', { class: 'fx-set__control' }, control));
+  const row = (label, hint, control) => settingRow({ label, hint, control });
 
   async function load() {
     let labels;

package/server/ui/mobile.js

@@ -68,6 +68,26 @@ export const RULES = {
     "mark": false,
     "card": "Button"
   },
+  "cardRows": {
+    "component": "cardRows",
+    "direction": "card per row",
+    "phone": {
+      "layout": "cards"
+    },
+    "tablet": {
+      "layout": "table"
+    },
+    "desk": {
+      "layout": "table"
+    },
+    "touch": 44,
+    "pageOverflow": "none",
+    "screens": [
+      "invoice",
+      "invoice-issued"
+    ],
+    "card": "CardRows"
+  },
   "columnTable": {
     "component": "columnTable",
     "direction": "two-line row",
@@ -281,6 +301,7 @@ export const RULES = {
     },
     "touch": 44,
     "pageOverflow": "none",
+    "scrollX": ".fx-frame, .fx-board, .fx-board-tabs",
     "screens": [
       "jobs-board",
       "jobs-list",
@@ -308,6 +329,7 @@ export const RULES = {
     },
     "touch": 44,
     "pageOverflow": "none",
+    "scrollX": ".fx-toolbar__tools",
     "screens": [
       "jobs-board",
       "jobs-list",
@@ -366,7 +388,8 @@ export const RULES = {
     "component": "notice",
     "direction": "note",
     "phone": {
-      "layout": "note"
+      "layout": "note",
+      "short": "one line in place of the title and text"
     },
     "tablet": {
       "layout": "note"
@@ -376,7 +399,9 @@ export const RULES = {
     },
     "touch": 44,
     "pageOverflow": "none",
-    "screens": [],
+    "screens": [
+      "invoice-offer"
+    ],
     "card": "Notice"
   },
   "optionPill": {
@@ -452,6 +477,23 @@ export const RULES = {
     "selector": ".fx-pager",
     "card": "Pager"
   },
+  "pickOne": {
+    "component": "pickOne",
+    "direction": "sheet list",
+    "phone": {
+      "layout": "sheet"
+    },
+    "tablet": {
+      "layout": "dialog"
+    },
+    "desk": {
+      "layout": "dialog"
+    },
+    "touch": 44,
+    "pageOverflow": "none",
+    "screens": [],
+    "card": "Pick"
+  },
   "rowMenu": {
     "component": "rowMenu",
     "direction": "menu",
@@ -511,7 +553,9 @@ export const RULES = {
     "touch": 44,
     "pageOverflow": "none",
     "screens": [
-      "appearance"
+      "appearance",
+      "integration-xero",
+      "integration-seazona"
     ],
     "card": "SettingRow"
   },
@@ -548,6 +592,7 @@ export const RULES = {
     },
     "touch": 44,
     "pageOverflow": "none",
+    "scrollX": ".fx-tabs",
     "screens": [
       "invoices-ready",
       "invoices-pending",

package/server/ui/price-list.js

@@ -34,7 +34,7 @@ const toCents = (text) => {
 };
 
 export async function renderPriceList(main, ui) {
-  const { h, flow, toast, notice, dialog, pageHeader, me } = ui;
+  const { h, flow, toast, notice, dialog, pageHeader, me, settingRow } = ui;
   const disabled = !['owner', 'admin'].includes(me?.person.role);
   const host = h('div', { class: 'fx-price' }, h('div', { class: 'fx-skeleton' }));
   let view = normaliseListView(me?.views?.['price-list'], PRICE_COLUMNS);
@@ -71,9 +71,7 @@ export async function renderPriceList(main, ui) {
     }
   }
 
-  const row = (name, hint, control) => h('div', { class: 'fx-set__row' },
-    h('div', { class: 'fx-set__text' }, h('span', { class: 'fx-set__name' }, name), hint),
-    h('div', { class: 'fx-set__control fx-rule__controls' }, control));
+  const row = (label, hint, control) => settingRow({ label, hint, control });
 
   const findingText = (f) => {
     const name = systemName(f.system);
@@ -165,7 +163,7 @@ export async function renderPriceList(main, ui) {
       else select.value = saved;
       select.disabled = disabled;
     });
-    return row('Line price from', h('span', { class: 'fx-set__hint' }, 'Where an invoice line takes its price.'), select);
+    return row('Line price from', 'Where an invoice line takes its price.', select);
   }
 
   function draw() {

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']);
-export 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', 'contacts.js', 'jobs.js', 'job-board.js', 'reconcile.js', 'xero-import.js', 'xero-usage.js', 'xero-usage-model.js', 'job-view.js', 'list-views.js', 'saved-views.js', 'monitoring.js', 'search.js', 'alerts.js', 'bulk-bar.js', 'view-bar.js', 'tip.js', 'kit.js', 'columns.js', 'mobile.js', 'person.js', 'pager.js', 'nav-pins.js', 'flow-mark.svg']);
+export 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', 'contacts.js', 'xero-contact.js', 'jobs.js', 'job-board.js', 'reconcile.js', 'xero-import.js', 'xero-usage.js', 'xero-usage-model.js', 'job-view.js', 'list-views.js', 'saved-views.js', 'monitoring.js', 'search.js', 'alerts.js', 'bulk-bar.js', 'view-bar.js', 'tip.js', 'kit.js', 'columns.js', 'mobile.js', 'person.js', 'pager.js', 'nav-pins.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/xero-contact.js

@@ -0,0 +1,101 @@
+// Link and Create for a Flow contact that is not a Xero contact
+// (docs/CONTACTS.md). The Pending invoice and the contact page both show
+// them. Link picks the Xero client when the names differ or Xero has the
+// name twice; Flow writes only its own link. Create adds the client to Xero.
+// `done(outcome)` runs after either one works.
+
+const SMALL = new Set(['the', 'and', 'of', 'pty', 'ltd', 'limited', 'co', 'inc']);
+
+function words(name) {
+  return new Set(String(name ?? '').toLowerCase().replace(/&/g, ' and ').replace(/[^a-z0-9]+/g, ' ').split(' ')
+    .filter((word) => word && !SMALL.has(word)));
+}
+
+// How many words two names share.
+export function closeness(a, b) {
+  const mine = words(a);
+  let shared = 0;
+  for (const word of words(b)) if (mine.has(word)) shared += 1;
+  return shared;
+}
+
+// The Xero contacts nearest the name first, then A to Z.
+export function nearestFirst(name, contacts) {
+  return contacts
+    .map((contact) => ({ contact, score: closeness(name, contact.name) }))
+    .sort((a, b) => b.score - a.score || a.contact.name.localeCompare(b.contact.name))
+    .map(({ contact }) => contact);
+}
+
+async function xeroContacts(ui, organisationId, q) {
+  const query = new URLSearchParams({ organisationId, q, limit: '1000' });
+  const { contacts } = await ui.flow(`/api/xero/contacts?${query}`);
+  return contacts.filter((contact) => contact.status === 'ACTIVE');
+}
+
+export function xeroContactActions(ui, { organisationId, contact, offerLink = false, offerCreate = false, done }) {
+  const { h, flow, toast } = ui;
+  const failed = (button, error) => {
+    toast(error.message, error.status === 429 ? 'info' : 'danger');
+    if (error.retryAfterMs) ui.holdButton(button, error.retryAfterMs);
+    else button.disabled = false;
+  };
+
+  const link = offerLink ? h('button', {
+    class: `fx-btn ${offerCreate ? 'fx-btn--ghost' : 'fx-btn--primary'}`, type: 'button', title: 'Link this client to its Xero client',
+    onclick: async (event) => {
+      const button = event.currentTarget;
+      const picked = await ui.pickOne({
+        title: `Link ${contact.name} to Xero`,
+        intro: 'Pick the Xero client. Flow links the two. Xero does not change.',
+        label: 'Xero clients',
+        find: 'Find a Xero client',
+        remote: true,
+        load: async (q) => nearestFirst(contact.name, await xeroContacts(ui, organisationId, q)),
+        item: (row) => ({ value: row.xeroContactId, title: row.name, meta: [row.email, row.accountNumber].filter(Boolean).join(' · ') }),
+        empty: 'No Xero client has that name. Sync Xero, or use Create.',
+        confirm: 'Link',
+      });
+      if (!picked) return;
+      button.disabled = true;
+      try {
+        await flow('/api/xero/contacts/link', { method: 'POST', body: JSON.stringify({ organisationId, contactId: contact.id, xeroContactId: picked.xeroContactId }) });
+        toast(`${contact.name} is linked to ${picked.name} in Xero.`, 'success');
+        await done('linked');
+      } catch (error) {
+        failed(button, error);
+      }
+    },
+  }, 'Link') : null;
+
+  const create = offerCreate ? h('button', {
+    class: 'fx-btn fx-btn--primary', type: 'button', title: 'Create this client in Xero',
+    onclick: async (event) => {
+      const button = event.currentTarget;
+      // A close name in Xero is often this client: say so before a second one.
+      let close = [];
+      try {
+        close = (await xeroContacts(ui, organisationId, '')).filter((row) => closeness(contact.name, row.name) > 0);
+      } catch { /* Create still works without the list. */ }
+      const names = nearestFirst(contact.name, close).slice(0, 3).map((row) => row.name);
+      const confirmed = await ui.dialog({
+        title: `Create ${contact.name} in Xero?`,
+        body: h('div', { class: 'fx-pick__body' },
+          h('p', {}, 'Flow adds this client to Xero from the contact.'),
+          names.length ? ui.notice(`Xero has ${names.join(', ')}. If one is this client, use Link.`, 'info', 'Close names.') : null),
+        confirm: 'Create',
+      });
+      if (!confirmed) return;
+      button.disabled = true;
+      try {
+        await flow('/api/xero/contacts', { method: 'POST', body: JSON.stringify({ organisationId, contactId: contact.id }) });
+        toast(`${contact.name} is in Xero.`, 'success');
+        await done('created');
+      } catch (error) {
+        failed(button, error);
+      }
+    },
+  }, 'Create') : null;
+
+  return [link, create].filter(Boolean);
+}