Skip to main content

ADR-0019 — In-situ editing as the primary UX path

  • Status: Accepted (2026-05-09). Implementation chassis reshaped through v0.6.332 + v0.6.383–386 — decision unchanged, vocabulary updated.
  • Decision-makers: Tom Anderson

Context​

Two ways to expose customization in a SaaS POS:

  • Settings-centric. Every customization lives in a settings tree. The user navigates to Settings → some sub-tab → finds the setting → changes it → navigates back. This is the dominant SaaS pattern (Lightspeed, Square, AIM all use it).
  • In-situ direct manipulation. Every customization is editable from where it lives. The Settings page still exists for things that aren't visible (API keys, integration creds) but is the secondary surface.

For Helm specifically:

  • Operators spend 30+ hours/week in the UI; small UX wins compound.
  • Bike shops accumulate "we should change that" frictions that never get fixed in Settings-centric systems.
  • AIM and Lightspeed don't have in-situ editing; the Hub doing it is a moat.

The cost: every editable element needs an in-situ pattern designed for it. The discipline is higher than just "throw it in Settings."

Decision​

In-situ editing is the primary UX path for every customizable element. The full philosophy is in in-situ-editing; the implementation chassis is helm-editable.

Specifically:

  • Every visible value editable from where it lives, via the helm-editable chassis — a single CSS + JS vocabulary used everywhere:
    • Inline value cell for single fields: dashed-underline cue on hover → contenteditable on click → auto-save on blur.
    • Composite-till modal for multi-field records (Service Slot ticket details, Trade-in intake, Customer card): same dashed-underline cue, but the click opens a per-till modal focused on the clicked field. Save once, parse, write back.
  • Permission gating: if the operator lacks edit permission for the surface, the helm-editable cells render as plain text without the hover affordance. Visible but uneditable; honest signal that a manager could change it.
  • Audit trail: every in-situ edit lands in audit_mutations via recordMutation with a per-surface trigger_source (customer-edit, slot-edit, tradein-edit, etc.). Same chain as server-driven mutations.
  • The Settings page exists for non-visible config (API keys, integration credentials, role definitions, tax registration numbers, shop hours, cron schedules) — anything that has no on-screen representation to edit in place.

This decision applies to every new screen. Retrofitting existing screens to follow the helm-editable chassis is a continuous process.

Consequences​

Positive:

  • Operators get a faster path to customization.
  • Onboarding is simpler — one chassis to learn (dashed-underline → click → edit), not a settings tree to memorize.
  • The Hub feels responsive in a way incumbents don't.
  • The discipline of "what should be in-situ vs. Settings" forces clarity about what's a configuration vs. what's a setting.
  • Aligns with progressive enhancement: the Settings page is the JS-light fallback.

Negative:

  • Every customizable element needs an inline editing experience designed and built.
  • More moving parts than a Settings-only design.
  • Permission, audit, and validation edge cases are per-surface.

Mitigations:

  • The helm-editable chassis is one CSS + JS vocabulary, shared across every surface — see helm-editable.
  • The composite-till modal pattern (v0.6.383–386) consolidates per-field contenteditable chains into one modal per till, cutting code surface dramatically while preserving the operator's mental model.

Notes​

The original (May 2026) phrasing of this ADR named a specific affordance — a circular bottom-right "K button" that toggled an edit mode revealing pencil glyphs, drag handles, and outlines. That implementation was retired through v0.6.332 (pencil-icon purge, three chasses unified under helm-editable) and v0.6.383–386 (composite-till modal pattern). The decision — in-situ editing is the primary UX path — survived unchanged. Only the chassis it manifests through evolved.

See also​