@arcforgelabs/flow 2026.10.25 → 2026.10.27

package/server/ui/invoice-rules.js

@@ -0,0 +1,237 @@
+// The "Rules" section of Settings, Invoicing (server/core/invoice-rules.js,
+// /api/invoicing/rules). Each rule a lab builds is a row: its name, one short
+// line that reads its conditions, and its switch. Edit opens a dialog where
+// every part is picked from a menu: the field, the test, and a value from
+// what Flow already holds (Seazona's statuses, the customers, the price list).
+// Everyone can read the rules; an owner or admin changes them. The caller
+// passes in app.js's shared pieces as `ui`.
+
+const DOCS = 'https://github.com/arcforgelabs/flow/blob/main/docs/INVOICE_RULES.md';
+
+const TEST_LABELS = {
+  more_than: 'is more than', at_most: 'is at most', is: 'is', is_not: 'is not', is_one_of: 'is one of',
+  is_empty: 'is empty', is_not_empty: 'is not empty', has: 'has', has_not: 'does not have',
+};
+const ACTION_LABELS = { wait: 'Wait for a person', skip: 'Never draft' };
+const NO_VALUE = ['is_empty', 'is_not_empty'];
+
+// A rule as one short line: "Job age (days) is more than 90 · Wait for a person".
+export function ruleSummary(rule, meta) {
+  const fieldOf = new Map(meta.fields.map((f) => [f.key, f]));
+  const labelOf = (field, value) => {
+    const option = (meta.options[field.options] ?? []).find((o) => String(o.value).toLowerCase() === String(value).toLowerCase());
+    return option?.label ?? String(value);
+  };
+  const part = (c) => {
+    const field = fieldOf.get(c.field);
+    if (!field) return c.field;
+    const test = TEST_LABELS[c.test] ?? c.test;
+    if (NO_VALUE.includes(c.test)) return `${field.label} ${test}`;
+    if (field.kind === 'boolean') return `${field.label} ${test} ${c.value ? 'yes' : 'no'}`;
+    if (field.kind === 'share') return `${labelOf(field, c.item).split(' · ')[0]} share ${test} ${c.value}%`;
+    if (field.kind === 'money') return `${field.label} ${test} $${Number(c.value).toFixed(2)}`;
+    const value = Array.isArray(c.value) ? c.value.map((v) => labelOf(field, v)).join(', ') : labelOf(field, c.value);
+    return `${field.label} ${test} ${value}`;
+  };
+  return `${rule.conditions.map(part).join(' and ')} · ${ACTION_LABELS[rule.action.kind] ?? rule.action.kind}`;
+}
+
+export function rulesSection(ui, title = 'Rules') {
+  const { h, flow, toast, notice, dialog, me } = ui;
+  const disabled = !['owner', 'admin'].includes(me?.person.role);
+  const section = h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, title), h('div', { class: 'fx-skeleton' }));
+  let meta;
+  let rules = [];
+
+  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 fx-rule__controls' }, control));
+
+  async function send(path, method, payload) {
+    try {
+      const body = await flow(path, { method, ...(payload ? { body: JSON.stringify(payload) } : {}) });
+      toast('Saved.', 'success');
+      return body;
+    } catch (error) {
+      toast(error.message, 'danger');
+      return null;
+    }
+  }
+
+  // One condition's controls: field, test and value, each a menu where Flow
+  // knows the values. `read()` answers the condition as the API takes it.
+  function conditionEditor(start, onRemove) {
+    const fieldSelect = h('select', { class: 'fx-select', 'aria-label': 'Field' },
+      meta.fields.map((f) => h('option', { value: f.key }, f.label)));
+    const testSelect = h('select', { class: 'fx-select', 'aria-label': 'Test' });
+    const valueHost = h('div', { class: 'fx-rule__value' });
+    let readValue = () => ({});
+
+    const options = (field) => meta.options[field.options] ?? [];
+    const choiceSelect = (field, value, label) => {
+      const list = options(field);
+      const select = h('select', { class: 'fx-select', 'aria-label': label },
+        list.map((o) => h('option', { value: o.value }, o.label)));
+      if (value !== undefined && !list.some((o) => String(o.value).toLowerCase() === String(value).toLowerCase())) {
+        select.append(h('option', { value }, String(value)));
+      }
+      if (value !== undefined) select.value = list.find((o) => String(o.value).toLowerCase() === String(value).toLowerCase())?.value ?? value;
+      return select;
+    };
+    const numberBox = (value, label) => h('input', { class: 'fx-input', type: 'number', min: '0', step: 'any', value: value ?? '', 'aria-label': label });
+
+    function drawValue(value, item) {
+      const field = meta.fields.find((f) => f.key === fieldSelect.value);
+      const test = testSelect.value;
+      valueHost.replaceChildren();
+      if (NO_VALUE.includes(test)) {
+        readValue = () => ({});
+      } else if (field.kind === 'boolean') {
+        const select = h('select', { class: 'fx-select', 'aria-label': 'Value' }, h('option', { value: 'true' }, 'Yes'), h('option', { value: 'false' }, 'No'));
+        select.value = String(value ?? false);
+        valueHost.append(select);
+        readValue = () => ({ value: select.value === 'true' });
+      } else if (field.kind === 'share') {
+        const items = choiceSelect(field, item, 'Line item');
+        const box = numberBox(value ?? 20, 'Percent of the other lines');
+        valueHost.append(items, box, h('span', { class: 'fx-dim' }, '%'));
+        readValue = () => ({ item: items.value, value: Number(box.value) });
+      } else if (['number', 'money'].includes(field.kind)) {
+        const box = numberBox(value, 'Value');
+        valueHost.append(box);
+        readValue = () => ({ value: Number(box.value) });
+      } else if (test === 'is_one_of') {
+        const chosen = new Set((Array.isArray(value) ? value : []).map((v) => String(v).toLowerCase()));
+        const boxes = options(field).map((o) => {
+          const box = h('input', { type: 'checkbox', value: o.value, checked: chosen.has(String(o.value).toLowerCase()) });
+          return h('label', { class: 'fx-multi__option' }, box, h('span', {}, o.label));
+        });
+        valueHost.append(h('div', { class: 'fx-rule__many' }, ...(boxes.length ? boxes : [h('span', { class: 'fx-dim' }, 'No values yet.')])));
+        readValue = () => ({ value: boxes.map((b) => b.querySelector('input')).filter((b) => b.checked).map((b) => b.value) });
+      } else if (field.options) {
+        const select = choiceSelect(field, Array.isArray(value) ? value[0] : value, 'Value');
+        valueHost.append(select);
+        readValue = () => ({ value: select.value });
+      } else {
+        const box = h('input', { class: 'fx-input', type: 'text', value: value ?? '', 'aria-label': 'Value' });
+        valueHost.append(box);
+        readValue = () => ({ value: box.value });
+      }
+    }
+
+    function drawTests(test) {
+      const field = meta.fields.find((f) => f.key === fieldSelect.value);
+      testSelect.replaceChildren(...field.tests.map((t) => h('option', { value: t }, TEST_LABELS[t] ?? t)));
+      testSelect.value = field.tests.includes(test) ? test : field.tests[0];
+    }
+
+    fieldSelect.value = start?.field ?? meta.fields[0].key;
+    drawTests(start?.test);
+    drawValue(start?.value, start?.item);
+    fieldSelect.addEventListener('change', () => { drawTests(); drawValue(); });
+    testSelect.addEventListener('change', () => drawValue());
+
+    const remove = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', 'aria-label': 'Remove condition' }, 'Remove');
+    const element = h('div', { class: 'fx-rule__condition' }, fieldSelect, testSelect, valueHost, remove);
+    remove.addEventListener('click', () => onRemove(element));
+    return { element, read: () => ({ field: fieldSelect.value, test: testSelect.value, ...readValue() }) };
+  }
+
+  // The dialog for a new rule (rule null) or an existing one. `draft` fills
+  // it again after a refused save, so no choice is lost.
+  async function edit(rule, draft = rule) {
+    const name = h('input', { class: 'fx-input', name: 'name', required: true, maxlength: '120', value: draft?.name ?? '', 'aria-label': 'Rule name' });
+    const action = h('select', { class: 'fx-select', 'aria-label': 'Then' },
+      Object.entries(ACTION_LABELS).map(([value, label]) => h('option', { value }, label)));
+    action.value = draft?.action.kind ?? 'wait';
+    let editors = [];
+    const list = h('div', { class: 'fx-rule__conditions' });
+    const addCondition = (start) => {
+      if (editors.length >= 10) return toast('A rule has 10 conditions at most.', 'danger');
+      const editor = conditionEditor(start, (element) => {
+        if (editors.length === 1) return toast('A rule needs at least one condition.', 'danger');
+        editors = editors.filter((e) => e.element !== element);
+        element.remove();
+        return null;
+      });
+      editors.push(editor);
+      list.append(editor.element);
+      return null;
+    };
+    for (const c of draft?.conditions ?? [null]) addCondition(c);
+    const more = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button' }, 'Add condition');
+    more.addEventListener('click', () => addCondition());
+
+    let wantsDelete = false;
+    const remove = rule ? h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm fx-rule__delete', type: 'button' }, 'Delete rule') : null;
+    remove?.addEventListener('click', () => {
+      wantsDelete = true;
+      remove.closest('dialog').close();
+    });
+
+    const label = (text, ...children) => h('div', { class: 'fx-field' }, h('span', { class: 'fx-label' }, text), ...children);
+    const data = await dialog({
+      title: rule ? 'Edit rule' : 'New rule',
+      body: h('div', { class: 'fx-fields fx-rule__dialog' },
+        label('Name', name),
+        label('When', h('span', { class: 'fx-dim' }, 'A job is ready to invoice and has no invoice.')),
+        label('If all of these match', list, more),
+        label('Then', action),
+        remove),
+      confirm: rule ? 'Save' : 'Add rule',
+    });
+    if (wantsDelete) {
+      const sure = await dialog({ title: `Delete "${rule.name}"?`, body: h('p', { class: 'fx-dim' }, 'Jobs stop waiting on this rule.'), confirm: 'Delete', tone: 'danger' });
+      if (sure && await send(`/api/invoicing/rules/${rule.id}`, 'DELETE')) rules = rules.filter((r) => r.id !== rule.id);
+      return draw();
+    }
+    if (!data) return null;
+    const payload = { name: name.value, conditions: editors.map((e) => e.read()), action: { kind: action.value } };
+    const body = rule
+      ? await send(`/api/invoicing/rules/${rule.id}`, 'PUT', payload)
+      : await send('/api/invoicing/rules', 'POST', payload);
+    if (!body) return edit(rule, payload);
+    rules = rule ? rules.map((r) => (r.id === rule.id ? body.rule : r)) : [...rules, body.rule];
+    return draw();
+  }
+
+  const rowOf = (rule) => {
+    const toggle = h('button', { class: 'fx-switch', type: 'button', role: 'switch', 'aria-label': rule.name, 'aria-checked': String(rule.enabled), disabled });
+    toggle.addEventListener('click', async () => {
+      toggle.disabled = true;
+      const body = await send(`/api/invoicing/rules/${rule.id}`, 'PUT', { enabled: toggle.getAttribute('aria-checked') !== 'true' });
+      toggle.disabled = disabled;
+      if (!body) return;
+      rules = rules.map((r) => (r.id === rule.id ? body.rule : r));
+      toggle.setAttribute('aria-checked', String(body.rule.enabled));
+    });
+    const controls = [toggle];
+    if (!disabled) {
+      const open = h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', 'aria-label': `Edit ${rule.name}` }, 'Edit');
+      open.addEventListener('click', () => edit(rule));
+      controls.unshift(open);
+    }
+    return row(rule.name, ruleSummary(rule, meta), controls);
+  };
+
+  function draw() {
+    const add = disabled ? null : h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button' }, 'Add rule');
+    add?.addEventListener('click', () => edit(null));
+    section.replaceChildren(
+      h('h2', { class: 'fx-set__title' }, title),
+      h('p', { class: 'fx-set__hint', style: { margin: '0 0 4px' } }, 'A ready job waits, or is never drafted, when a rule matches.'),
+      ...(rules.length ? rules.map(rowOf) : [h('p', { class: 'fx-dim' }, 'No rules. Every ready job is drafted.')]),
+      h('div', { class: 'fx-rule__footer' }, add,
+        h('a', { class: 'fx-dim', href: DOCS, target: '_blank', rel: 'noopener' }, 'How rules work')));
+  }
+
+  (async () => {
+    try {
+      [meta, { rules }] = await Promise.all([flow('/api/invoicing/rule-fields'), flow('/api/invoicing/rules')]);
+      draw();
+    } catch (error) {
+      section.replaceChildren(h('h2', { class: 'fx-set__title' }, title), notice(error.message, 'danger'));
+    }
+  })();
+  return section;
+}

package/server/ui/invoicing-settings.js

@@ -0,0 +1,108 @@
+// Settings, Invoicing (/invoicing-settings): payment terms, the draft
+// automation, and the lab's own rules a ready job passes before Flow drafts
+// its invoice (invoice-rules.js, docs/INVOICE_RULES.md). Invoicing needs no integration: how an invoice
+// goes to Xero is on the Xero integration page (sendModeSection).
+// Draft when ready is an automation (server/core/automations.js); the
+// Seazona integration page holds the rule that marks a job ready.
+// One row for each setting: its name, one short line, and its control. A
+// change saves at once. Everyone can read them; an owner or admin changes
+// them. The full rules are in docs/INVOICING_RULES.md. app.js passes in its
+// shared pieces as `ui`.
+
+import { automationSection } from '/assets/ui/automations.js';
+import { rulesSection } from '/assets/ui/invoice-rules.js';
+
+const DOCS = 'https://github.com/arcforgelabs/flow/blob/main/docs/INVOICING_RULES.md';
+
+const SEND_MODES = [
+  { value: 'accounting_draft', label: 'Xero draft' },
+  { value: 'approve_and_email', label: 'Approved and emailed' },
+];
+
+export async function renderInvoicingSettings(main, ui) {
+  const { h, flow, toast, notice, pageHeader, me } = ui;
+  const host = h('div', { class: 'fx-card', style: { padding: '8px 20px 16px' } }, h('div', { class: 'fx-skeleton' }));
+  main.append(pageHeader('Invoicing', { subtitle: 'How Flow drafts invoices. No integration needed.' }), host);
+  let body;
+  try {
+    body = await flow('/api/invoicing/settings');
+  } catch (error) {
+    host.replaceChildren(notice(error.message, 'danger'));
+    return;
+  }
+  const disabled = !['owner', 'admin'].includes(me?.person.role);
+  let saved = body.settings;
+
+  async function save(changes, control) {
+    control.disabled = true;
+    try {
+      saved = (await flow('/api/invoicing/settings', { method: 'PUT', body: JSON.stringify(changes) })).settings;
+      toast('Saved.', 'success');
+      return true;
+    } catch (error) {
+      toast(error.message, 'danger');
+      return false;
+    } finally {
+      control.disabled = false;
+    }
+  }
+
+  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));
+
+  // A text or number box saves when it loses focus with a new value.
+  const box = (key, label, { type = 'text', read = (v) => v, show = (v) => v ?? '', placeholder } = {}) => {
+    const input = h('input', { class: 'fx-input', type, value: show(saved[key]), 'aria-label': label, disabled, placeholder });
+    input.addEventListener('change', async () => {
+      if (!(await save({ [key]: read(input.value) }, input))) input.value = show(saved[key]);
+    });
+    return input;
+  };
+  const days = (key, label) => box(key, label, { type: 'number', read: Number });
+
+  const section = (title, ...rows) => h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, title), ...rows);
+  host.replaceChildren(...[
+    disabled ? notice('Only an owner or admin can change these.', 'info') : null,
+    section('Drafts',
+      row('Payment terms', 'Days from invoice to due date.', days('paymentTermsDays', 'Payment terms in days'))),
+    automationSection(ui, 'invoicing', 'Automations'),
+    rulesSection(ui),
+  ].filter(Boolean));
+}
+
+// The Xero integration page's "Sending" section: how a checked invoice goes to
+// Xero. A customer can have its own mode (/api/invoicing/contacts/:id/billing).
+export function sendModeSection(ui) {
+  const { h, flow, toast, notice, me } = ui;
+  const disabled = !['owner', 'admin'].includes(me?.person.role);
+  const select = h('select', { class: 'fx-select', 'aria-label': 'Send to Xero as', disabled },
+    SEND_MODES.map((m) => h('option', { value: m.value }, m.label)));
+  const section = h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, 'Sending'),
+    h('div', { class: 'fx-set__row' },
+      h('div', { class: 'fx-set__text' }, h('span', { class: 'fx-set__name' }, 'Send to Xero as'), h('span', { class: 'fx-set__hint' }, 'Draft: approve in Xero. Approved: Xero emails it.')),
+      h('div', { class: 'fx-set__control' }, select)),
+    h('p', { class: 'fx-dim', style: { margin: '8px 0 0' } }, h('a', { href: DOCS, target: '_blank', rel: 'noopener' }, 'How sending works')));
+  let saved = null;
+  (async () => {
+    try {
+      saved = (await flow('/api/invoicing/settings')).settings;
+      select.value = saved.sendMode;
+    } catch (error) {
+      section.append(notice(error.message, 'danger'));
+    }
+  })();
+  select.addEventListener('change', async () => {
+    select.disabled = true;
+    try {
+      saved = (await flow('/api/invoicing/settings', { method: 'PUT', body: JSON.stringify({ sendMode: select.value }) })).settings;
+      toast('Saved.', 'success');
+    } catch (error) {
+      toast(error.message, 'danger');
+      if (saved) select.value = saved.sendMode;
+    } finally {
+      select.disabled = disabled;
+    }
+  });
+  return section;
+}