@arcforgelabs/flow 2026.10.42 → 2026.10.43

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.42",
+  "version": "2026.10.43",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.42",
+      "version": "2026.10.43",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.42",
+  "version": "2026.10.43",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/integrations/sentry/index.js

@@ -42,6 +42,7 @@ export const SENTRY_SETUP = {
   fields: [
     { name: 'SENTRY_DSN', label: 'DSN', kind: 'url', help: 'From the Sentry project\'s Client Keys. Browsers see it, so it is not a secret.' },
     { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production, or workspace in a Replit workspace.' },
+    { name: 'SENTRY_CLIENT', label: 'Client', help: 'The name your support desk files this installation\'s reports under. Sent as the client tag. Empty: no client tag.' },
     { name: 'SENTRY_FEEDBACK', label: 'Report a problem button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
     { name: 'SENTRY_TRACES_SAMPLE_RATE', label: 'Traces', help: 'The share of clicks, page loads and requests timed, from 0 (off) to 1 (all). Empty: 0.2.' },
   ],
@@ -60,7 +61,12 @@ export function readSentrySettings(env) {
   if (!/^\d*\.?\d+$/.test(rate || '0') || !(tracesSampleRate >= 0 && tracesSampleRate <= 1)) {
     throw new Error('SENTRY_TRACES_SAMPLE_RATE must be a number from 0 to 1, such as 0.2.');
   }
-  return { dsn, environment, feedback, tracesSampleRate };
+  const client = String(env.SENTRY_CLIENT ?? '').trim();
+  if (client.length > 60 || /[\r\n]/.test(client)) throw new Error('SENTRY_CLIENT must be one short line.');
+  // Every event says which product and, when set, which client it is from,
+  // so one support desk can serve many installations.
+  const tags = client ? { product: 'flow', client } : { product: 'flow' };
+  return { dsn, environment, feedback, tracesSampleRate, tags };
 }
 
 // No trace for the host's health check: it is not a person waiting.
@@ -92,6 +98,7 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
         dsn: settings.dsn,
         environment: settings.environment,
         release: release ?? undefined,
+        initialScope: { tags: settings.tags },
         // Flow sends what it logs; no request bodies, cookies or IP addresses.
         sendDefaultPii: false,
         // A request the browser traced keeps the browser's choice, so a
@@ -132,6 +139,7 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
           environment: settings.environment,
           release,
           feedback: settings.feedback,
+          tags: settings.tags,
           tracesSampleRate,
           script: tracesSampleRate > 0 ? SENTRY_BROWSER_TRACING : SENTRY_BROWSER,
         };

package/server/ui/app-page.js

@@ -51,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list', '/custom-fields'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/invoicing-settings/:id', '/automations', '/price-list', '/custom-fields'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({

package/server/ui/app.js

@@ -10,7 +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 { automationSection } from '/assets/ui/automations.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';
 import { renderPriceReconcile } from '/assets/ui/price-reconcile.js';
@@ -21,6 +21,7 @@ import { renderXeroImport } from '/assets/ui/xero-import.js';
 import { startMonitoring } from '/assets/ui/monitoring.js';
 import { openSearch } from '/assets/ui/search.js';
 import { alertStrip } from '/assets/ui/alerts.js';
+import { named, startTips } from '/assets/ui/tip.js';
 
 const $ = (id) => document.getElementById(id);
 
@@ -164,14 +165,28 @@ function holdButton(button, ms) {
 
 // ── Shared pieces ──────────────────────────────────────────────────────────
 
-function pageHeader(title, { subtitle, actions = [] } = {}) {
+// The page's name and nothing under it: the page shows what it is for.
+// `count` is a live number beside the name (2 to check); `help` is a docs
+// link, an icon with its name as a tip.
+function pageHeader(title, { count = null, help = null, actions = [] } = {}) {
   return h('header', { class: 'fx-ph' },
     h('div', { class: 'fx-ph__text' },
       h('h1', { class: 'fx-title' }, title),
-      subtitle ? h('p', { class: 'fx-ph__sub' }, subtitle) : null),
+      count != null ? h('span', { class: 'fx-ph__count' }, count) : null,
+      help ? helpLink(help) : null),
     actions.length ? h('div', { class: 'fx-ph__actions' }, actions) : null);
 }
 
+// A docs link as a small "?" icon whose tip names it (How sending works).
+function helpLink({ href, label }) {
+  return named(h('a', { class: 'fx-help', href, target: '_blank', rel: 'noopener' }, lucide(h, 'circle-help')), label);
+}
+
+// A settings section's heading, with its docs link beside it.
+function sectionTitle(text, help = null) {
+  return h('h2', { class: 'fx-set__title' }, text, help ? helpLink(help) : null);
+}
+
 function notice(text, tone = 'info', title = null) {
   return h('div', { class: 'fx-notice', 'data-tone': tone, role: tone === 'danger' ? 'alert' : 'status' },
     title ? h('strong', {}, title) : null,
@@ -235,7 +250,8 @@ const VIEWS = {
   jobs: { label: 'Jobs', icon: 'jobs', group: 'Work', render: (main) => renderJobs(main, ui()) },
   invoices: { label: 'Invoices', icon: 'invoices', group: 'Work', render: (main, id) => (id ? renderInvoice(main, ui(), id) : renderInvoiceList(main, ui())) },
   reconcile: { label: 'Reconcile', icon: 'reconcile', group: 'Work', render: (main, id) => renderReconcile(main, ui(), id) },
-  'invoicing-settings': { label: 'Invoice rules', icon: 'invoices', group: 'Settings', render: (main) => renderInvoicingSettings(main, ui()) },
+  'invoicing-settings': { label: 'Rules', icon: 'rules', group: 'Settings', render: (main, id) => renderInvoicingSettings(main, ui(), id) },
+  automations: { label: 'Automations', icon: 'bolt', group: 'Settings', render: (main) => renderAutomations(main, ui()) },
   'price-list': { label: 'Price list', icon: 'tag', group: 'Settings', render: (main, id) => (id === 'reconcile' ? renderPriceReconcile(main, ui()) : renderPriceList(main, ui())) },
   'custom-fields': { label: 'Custom fields', icon: 'fields', group: 'Settings', render: (main) => renderCustomFields(main, ui()) },
   people: { label: 'People', icon: 'people', group: 'Settings', ownerOnly: true, render: renderPeople },
@@ -252,6 +268,9 @@ 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"/>',
+  draft: '<path d="M14 3H6v18h5M14 3l4 4v3M14 3v4h4"/><path d="M13 21v-2.5l6-6 2.5 2.5-6 6z"/>',
+  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"/>',
   people: '<circle cx="9" cy="8" r="3"/><path d="M3 20c0-3.5 2.7-6 6-6s6 2.5 6 6"/><path d="M16 5a3 3 0 010 6M21 20c0-3-1.6-5-4-5.7"/>',
   tag: '<path d="M3 12V4h8l10 10-8 8z"/><circle cx="7.5" cy="8.5" r="1.5"/>',
@@ -292,11 +311,11 @@ function drawMenu() {
   const label = NARROW.matches ? (open ? 'Close the menu' : 'Open the menu') : (folded ? 'Show the sidebar' : 'Hide the sidebar');
   toggle.setAttribute('aria-expanded', String(open));
   toggle.setAttribute('aria-label', label);
-  toggle.title = label;
+  toggle.dataset.tip = label;
   // Folded, a page's name shows when the pointer rests on its icon.
   for (const link of document.querySelectorAll('[data-nav]')) {
-    if (folded && !NARROW.matches) link.title = link.dataset.label;
-    else link.removeAttribute('title');
+    if (folded && !NARROW.matches) Object.assign(link.dataset, { tip: link.dataset.label, tipSide: 'right' });
+    else { delete link.dataset.tip; delete link.dataset.tipSide; }
   }
 }
 
@@ -403,7 +422,7 @@ function navigate(event) {
 // The shared pieces a view module (invoicing.js) builds with. Its `go`
 // takes a path, or a link's click event.
 const ui = () => ({
-  h, flow, toast, notice, pageHeader, dialog, me, holdButton,
+  h, flow, toast, notice, pageHeader, sectionTitle, dialog, me, holdButton, tileCard, crumbs,
   go: (target, options) => (typeof target === 'string' ? go(target, options) : navigate(target)),
 });
 
@@ -641,9 +660,9 @@ async function renderIntegrations(main) {
   const notices = h('div', { class: 'fx-fields' });
   const content = h('div', { class: 'fx-int-sections' }, h('div', { class: 'fx-skeleton' }));
   main.append(
-    h('header', { class: 'fx-ph' }, h('div', { class: 'fx-ph__text' }, h('h1', { class: 'fx-title' }, 'Integrations'))),
+    pageHeader('Integrations'),
     alertStrip(ui(), 'integrations').element,
-    h('div', { class: 'fx-int-bar' }, tabs, search),
+    h('div', { class: 'fx-int-bar' }, tabs, h('div', { class: 'fx-row' }, category, search)),
     notices, content);
   let body;
   try {
@@ -655,13 +674,14 @@ async function renderIntegrations(main) {
   const canChange = Boolean(me.ownerActions?.allowed);
   notices.replaceChildren(...[
     canChange ? null : notice('Changing integrations needs a verified owner sign-in: Google Workspace on the owner domain with no password, or a second factor.', 'warn', 'Read only.'),
-    body.secretsKey ? null : notice('Flow has no secrets key, so it cannot store a client secret. Ask whoever hosts Flow to set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.'),
+    body.secretsKey ? null : notice('Flow cannot store a client secret. Set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.'),
   ].filter(Boolean));
   const list = [...body.integrations].sort((a, b) => a.name.localeCompare(b.name));
   const connected = (i) => i.enabled;
 
   const draw = () => {
-    tabs.replaceChildren(...[['all', 'All integrations'], ['yours', 'Your integrations']].map(([id, label]) => h('button', {
+    category.hidden = state.tab !== 'all';
+    tabs.replaceChildren(...[['all', 'All'], ['yours', 'Connected']].map(([id, label]) => h('button', {
       type: 'button', role: 'tab', class: 'fx-seg__item', 'aria-selected': String(state.tab === id), 'aria-checked': String(state.tab === id),
       onclick: () => { state.tab = id; draw(); },
     }, label)));
@@ -672,7 +692,7 @@ async function renderIntegrations(main) {
       const yours = list.filter(connected).filter(matches);
       sections.push(h('section', { class: 'fx-int-section-list' },
         yours.length ? h('div', { class: 'fx-int-grid' }, yours.map(integrationTile))
-          : h('p', { class: 'fx-empty' }, q ? 'No integration matches.' : 'Nothing is connected yet. Pick one under All integrations.')));
+          : h('p', { class: 'fx-empty' }, q ? 'No integration matches.' : 'Nothing is connected yet. Pick one under All.')));
     } else {
       // Recommended: what is not connected yet, once the catalogue is long
       // enough that a short row helps (with a few, it would repeat the grid).
@@ -684,7 +704,7 @@ async function renderIntegrations(main) {
       }
       const all = list.filter(matches).filter((i) => state.category === 'all' || CATALOGUE[i.id]?.category === state.category);
       sections.push(h('section', { class: 'fx-int-section-list' },
-        h('div', { class: 'fx-int-heading-row' }, h('h2', { class: 'fx-int-heading' }, 'All integrations'), category),
+        recommended.length ? h('h2', { class: 'fx-int-heading' }, 'All') : null,
         all.length ? h('div', { class: 'fx-int-grid' }, all.map(integrationTile)) : h('p', { class: 'fx-empty' }, 'No integration matches.')));
     }
     content.replaceChildren(...sections);
@@ -695,17 +715,39 @@ async function renderIntegrations(main) {
 }
 
 function integrationTile(integration) {
-  const href = `/integrations/${integration.id}`;
   const entry = CATALOGUE[integration.id];
   const on = integration.enabled;
   const attention = ['failed', 'restart_needed'].includes(integration.state);
-  return h('a', { class: 'fx-int-card', href, onclick: navigate },
+  return tileCard({
+    href: `/integrations/${integration.id}`,
+    mark: integrationLogo(integration),
+    title: integration.name,
+    status: on ? { label: STATE_LABEL[integration.state] ?? integration.state, tone: STATE_TONE[integration.state] } : null,
+    blurb: entry?.blurb,
+    action: attention ? 'Fix' : on ? 'Manage' : '+ Connect',
+  });
+}
+
+// One card in a grid of choices (Integrations, Rules): its mark (a node, or
+// an ICON_PATHS name), the name, a status pill, two lines at most (only when
+// they help), and the action. The whole card is the link.
+function tileCard({ href, mark, title, status, blurb, action = 'Manage' }) {
+  const logo = typeof mark === 'string' ? h('span', { class: 'fx-logo fx-logo--icon', 'aria-hidden': 'true' }, icon(mark)) : mark;
+  return h('a', { class: `fx-int-card${blurb ? '' : ' fx-int-card--bare'}`, href, onclick: navigate },
     h('header', { class: 'fx-int-card__head' },
-      integrationLogo(integration),
-      h('h3', {}, integration.name),
-      on ? h('span', { class: 'fx-status', 'data-tone': STATE_TONE[integration.state] ?? 'mute' }, STATE_LABEL[integration.state] ?? integration.state) : null),
-    h('p', { class: 'fx-int-card__blurb' }, entry?.blurb ?? ''),
-    h('span', { class: 'fx-int-card__btn' }, attention ? 'Fix' : on ? 'Manage' : '+ Connect'));
+      logo,
+      h('h3', {}, title),
+      status ? h('span', { class: 'fx-status', 'data-tone': status.tone ?? 'mute' }, status.label) : null),
+    blurb ? h('p', { class: 'fx-int-card__blurb' }, blurb) : null,
+    h('span', { class: 'fx-int-card__btn' }, action));
+}
+
+// The trail above a page one level down: crumbs(['/integrations', 'Integrations'], 'Xero').
+function crumbs(...trail) {
+  const here = trail.pop();
+  return h('nav', { class: 'fx-crumbs', 'aria-label': 'Breadcrumb' },
+    ...trail.flatMap(([href, label]) => [h('a', { href, onclick: navigate }, label), h('span', { 'aria-hidden': 'true' }, '›')]),
+    h('span', {}, here));
 }
 
 // One integration's page (/integrations/<id>): its logo and maker, Connect
@@ -842,8 +884,7 @@ async function renderIntegration(main, id) {
         busy ? h('span', { class: 'fx-spinner fx-spinner--sm', 'aria-hidden': 'true' }) : null, busy ? 'Connecting' : 'Connect');
 
     host.replaceChildren(
-      h('nav', { class: 'fx-crumbs', 'aria-label': 'Breadcrumb' },
-        h('a', { href: '/integrations', onclick: navigate }, 'Integrations'), h('span', { 'aria-hidden': 'true' }, '›'), h('span', {}, current.name)),
+      crumbs(['/integrations', 'Integrations'], current.name),
       h('header', { class: 'fx-int-hero' },
         integrationLogo(current, 'xl'),
         h('div', { class: 'fx-int-hero__text' },
@@ -858,7 +899,7 @@ async function renderIntegration(main, id) {
         h('div', { class: 'fx-int-page__main' }, ...[
           alerts.element,
           !canChange ? notice('Changing integrations needs a verified owner sign-in: Google Workspace on the owner domain with no password, or a second factor.', 'warn', 'Read only.') : null,
-          !body.secretsKey ? notice('Flow has no secrets key, so it cannot store a client secret. Ask whoever hosts Flow to set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.') : null,
+          !body.secretsKey ? notice('Flow cannot store a client secret. Set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.') : null,
           current.state === 'failed' && current.error ? notice(current.error, 'danger', 'It could not start.') : null,
           current.id === 'xero' && current.state === 'ready' ? h('section', { class: 'fx-int-section' }, xeroConnection(body.organisations, canChange)) : null,
           current.id === 'seazona' ? h('section', { class: 'fx-int-section fx-card', style: { padding: '8px 20px 16px' } }, automationSection(ui(), 'seazona', 'Ready to invoice')) : null,
@@ -1103,7 +1144,7 @@ function renderAccount(main) {
 // in it at once.
 function renderAppearance(main) {
   main.append(
-    pageHeader('Appearance', { subtitle: 'Saved with your account, on every device.' }),
+    pageHeader('Appearance'),
     h('div', { class: 'fx-appearance', id: 'appearance' }));
   drawAppearance();
 }
@@ -1169,13 +1210,16 @@ function drawAppearance() {
     (p) => chooseAppearance({ accent: p.hex ? p.id : null }),
     (p) => p.hex
       ? h('button', { type: 'button', class: 'fx-swatch', title: p.label, 'aria-label': p.label, style: { background: p.hex } })
-      : h('button', { type: 'button', class: 'fx-swatch fx-swatch--default', title: `${active.label}'s own`, 'aria-label': `${active.label}'s own accent` },
-        h('span', { 'aria-hidden': 'true', style: { background: `linear-gradient(135deg, ${active.swatches[mode].primary} 50%, ${active.swatches[mode].accent} 50%)` } })));
+      // The design system's own accent, named "Default" on the swatch: a
+      // click puts it back.
+      : h('button', { type: 'button', class: 'fx-swatch fx-swatch--default', 'aria-label': `Default: ${active.label}'s own accent` },
+        h('span', { class: 'fx-swatch__dot', 'aria-hidden': 'true', style: { background: `linear-gradient(135deg, ${active.swatches[mode].primary} 50%, ${active.swatches[mode].accent} 50%)` } }),
+        'Default'));
   accents.classList.add('fx-swatches');
   const custom = h('label', { class: 'fx-swatch-custom' },
     h('input', { type: 'color', 'aria-label': 'Custom accent colour', value: customHex ?? '#0d4e5f', onchange: (event) => chooseAppearance({ accent: event.target.value }) }),
     'Custom');
-  const accentLabel = customHex ? `Custom ${customHex}` : presetIndex > 0 ? ACCENT_PRESETS[presetIndex].label : `${active.label}'s own`;
+  const accentLabel = customHex ? `Custom ${customHex}` : presetIndex > 0 ? ACCENT_PRESETS[presetIndex].label : `the default, ${active.label}'s own`;
 
   host.replaceChildren(h('div', { class: 'fx-settings' },
     settingRow({ label: 'Mode', hint: 'Auto follows this device.', control: modeGroup }),
@@ -1230,7 +1274,7 @@ function drawModeToggles() {
     button.innerHTML = dark ? SUN : MOON;
     if (!button.classList.contains('fx-btn--icon')) button.append(` ${dark ? 'Light' : 'Dark'}`);
     button.setAttribute('aria-label', label);
-    button.title = label;
+    button.dataset.tip = label;
   }
 }
 
@@ -1291,4 +1335,5 @@ async function start() {
   await renderShell();
 }
 
+startTips();
 start();

package/server/ui/automations.js

@@ -1,6 +1,6 @@
 // Automation rows (server/core/automations.js, /api/invoicing/automations).
 // Each automation shows where its trigger lives: the work system's ready rule
-// on that integration's page, the draft rule on Settings, Invoicing. One row
+// on that integration's page, the invoicing ones on Settings, Automations. One row
 // for each: its name, one short line, and its switch, plus a row for each of
 // its settings. A change saves at once. Everyone can read them; an owner or
 // admin changes them. The caller passes in app.js's shared pieces as `ui`.
@@ -86,11 +86,17 @@ export function automationSection(ui, place, title) {
   (async () => {
     try {
       const { automations } = await flow(`/api/invoicing/automations?place=${encodeURIComponent(place)}`);
-      section.replaceChildren(h('h2', { class: 'fx-set__title' }, title), ...automations.flatMap(rowsOf),
-        h('p', { class: 'fx-dim', style: { margin: '8px 0 0' } }, h('a', { href: DOCS, target: '_blank', rel: 'noopener' }, 'How automations work')));
+      section.replaceChildren(ui.sectionTitle(title, { href: DOCS, label: 'How automations work' }), ...automations.flatMap(rowsOf));
     } catch (error) {
       section.replaceChildren(h('h2', { class: 'fx-set__title' }, title), notice(error.message, 'danger'));
     }
   })();
   return section;
 }
+
+// Settings, Automations (/automations): the invoicing automations. A work
+// system's own automations stay on its integration page.
+export function renderAutomations(main, ui) {
+  const { h, pageHeader } = ui;
+  main.append(pageHeader('Automations'), h('div', { class: 'fx-card', style: { padding: '8px 20px 16px' } }, automationSection(ui, 'invoicing', 'Invoicing')));
+}

package/server/ui/custom-fields.js

@@ -14,6 +14,7 @@
 // passes in app.js's shared pieces as `ui`.
 
 import { orderStatuses, statusRank } from '/assets/ui/job-board.js';
+import { sidecar } from '/assets/ui/sidecar.js';
 
 const DOCS = 'https://github.com/arcforgelabs/flow/blob/main/docs/CUSTOM_FIELDS.md';
 const TYPE_LABELS = {
@@ -96,7 +97,7 @@ export async function renderCustomFields(main, ui) {
   const disabled = !['owner', 'admin'].includes(me?.person.role);
   const host = h('div', { class: 'fx-card fx-cfm__card' }, h('div', { class: 'fx-skeleton' }));
   const addButton = h('button', { class: 'fx-btn fx-btn--primary fx-btn--sm', type: 'button', disabled }, 'Create custom field');
-  main.append(pageHeader('Custom fields', { subtitle: 'Fields for your jobs. They stay in Flow and never change Seazona or Xero.' }), host);
+  main.append(pageHeader('Custom fields', { help: { href: DOCS, label: 'How custom fields work' } }), host);
 
   let data = null;
   const groupColor = (type) => data?.groupColors?.[type] ?? 'gray';
@@ -157,17 +158,19 @@ export async function renderCustomFields(main, ui) {
   // the manager. Edit on a row (or Create) opens it; another row's Edit
   // switches it at once, so a person moves between fields quickly. The
   // table stays usable behind it. Save closes it; so do Cancel, × and Esc.
-  const side = h('aside', { class: 'fx-cfs', 'aria-label': 'Custom field', hidden: true });
-  let sideFor = null;
-  function closeSide() {
-    side.hidden = true;
-    side.replaceChildren();
-    sideFor = null;
-    table.querySelector('.fx-cfm__row[data-open]')?.removeAttribute('data-open');
-  }
-  document.addEventListener('keydown', (event) => {
-    if (event.key === 'Escape' && side.isConnected && !side.hidden && !document.querySelector('dialog[open], .fx-pop:popover-open')) closeSide();
+  // The shared sidecar (sidecar.js), over the table.
+  const panel = sidecar(h, {
+    label: 'Custom field', overlay: true, escape: true,
+    onChange: (tab) => {
+      if (tab !== null) return;
+      sideFor = null;
+      table.querySelector('.fx-cfm__row[data-open]')?.removeAttribute('data-open');
+    },
   });
+  const side = panel.element;
+  side.classList.add('fx-cfs');
+  let sideFor = null;
+  const closeSide = () => panel.close();
 
   // Open the sidecar for a field (null: a new one; `draft` fills it after a
   // failed save). A work system's field opens read only.
@@ -188,7 +191,7 @@ export async function renderCustomFields(main, ui) {
     // lies over the label, so the label shows and the browser's list opens.
     const typeText = h('span', {}, TYPE_LABELS[type.value]);
     const headType = field ? typeLabel() : h('label', { class: 'fx-cfs__typepick' }, lucide(h, TYPE_ICONS[type.value]), typeText, lucide(h, 'chevron-down'), type);
-    const close = h('button', { class: 'fx-cfs__close', type: 'button', 'aria-label': 'Close', onclick: closeSide }, lucide(h, 'x'));
+    const close = panel.closeButton();
 
     const name = h('input', { class: 'fx-cfs__name', required: true, maxlength: '60', value: draft?.name ?? '', 'aria-label': 'Custom field name', placeholder: 'For example Priority', readonly: readOnly });
     name.addEventListener('input', changed);
@@ -245,10 +248,9 @@ export async function renderCustomFields(main, ui) {
       await load();
     });
     fit();
-    side.replaceChildren(form);
+    panel.show(form);
     // Below the toolbar, so search and Create stay in reach.
     side.style.top = `${toolbar.offsetHeight}px`;
-    side.hidden = false;
     table.querySelector('.fx-cfm__row[data-open]')?.removeAttribute('data-open');
     if (field) table.querySelector(`.fx-cfm__row[data-id="${CSS.escape(field.id)}"]`)?.setAttribute('data-open', 'true');
     (readOnly ? close : name).focus({ preventScroll: true });
@@ -493,8 +495,7 @@ export async function renderCustomFields(main, ui) {
     }
     table.replaceChildren(...parts);
     // The count is what the table shows, the work systems' fields too.
-    foot.replaceChildren(h('span', {}, `${count} ${count === 1 ? 'custom field' : 'custom fields'}`),
-      h('a', { href: DOCS, target: '_blank', rel: 'noopener' }, 'How custom fields work'));
+    foot.replaceChildren(h('span', {}, `${count} ${count === 1 ? 'custom field' : 'custom fields'}`));
   }
   const foot = h('div', { class: 'fx-cfm__foot' });
   host.append(foot);