Note (2026-04-24): After this document was written, legal_entity was renamed to tenant and the old tenant was renamed to organization. Read references to these terms with the pre-rename meaning.

Account Master Data Picker Design

Goal

Replace the current two-field inline editing for line-item debit account, credit account, and cost center with a single picker control per field, populated from legal-entity master data.

Scope

This design covers:

• debit account editor
• credit account editor
• cost center editor
• transport of master data from backend to frontend
• client-side filtering behavior inside the picker

This design does not cover:

• free-text fallback editing
• server-side filtering
• broader inline editing refactors outside these three fields

Current Problem

The current line-item UI renders debit and credit account as two separate editable fields each: one for :number and one for :name. Issue #358 requires replacing that with a single field, preferably backed by master data. Cost centers should follow the same transport and picker pattern.

Decision Summary

Transport

Use an HTMX endpoint that returns an editor fragment on demand.

The initial document detail page will not preload GL accounts or cost centers into the HTML. When the user activates one of the supported fields, HTMX requests a field-specific editor fragment from the backend. That fragment includes:

• field metadata needed by the editor
• the current selected structured value
• a category-specific master-data payload embedded in the fragment
• the picker shell markup

The endpoint returns only one category per request:

• gl-accounts for debit/credit account fields
• cost-centers for cost center fields

Filtering

Use client-side filtering only.

Assumption: each legal entity will remain below roughly 500 items per category, so loading the full category dataset into the editor fragment is acceptable.

Filtering is case-insensitive substring matching over:

• number
• name
• employee for cost centers when present

There is no server-side search and no fuzzy search in this design.

UI Control

Use a custom single-field combobox, not a native <select> or <datalist>.

The combobox is loaded via HTMX and then filters locally in JavaScript against the embedded dataset.

Master Data Payload Shape

GL Accounts

[{:number "4000"
  :name "Travel Expense"}]

Cost Centers

[{:number "CC-100"
  :name "Operations"
  :employee "Max Mustermann"}]

Notes:

• There is no synthetic id.
• number is the business key used by the picker.
• There is no precomputed search-text.
• Filtering is computed in the browser from the visible fields.

Interaction Design

Rest State

Each supported field is rendered as a single combined display value.

Examples:

• debit account: 4000 Travel Expense
• credit account: 120000 Kreditoren
• cost center: CC-100 Operations - Max Mustermann

Edit State

Clicking the field swaps the display node via HTMX for an editor fragment.

The fragment contains:

• a text input
• the embedded dataset for that category
• a result list
• the current selected structured value

Filtering Behavior

Typing into the input filters the dataset locally in JavaScript.

Matching rules:

• case-insensitive
• substring match only
• search number
• search name
• search employee when present

Selection Behavior

Selecting a result commits the structured fields, not the combined display string.

For GL accounts, selection writes:

• :number
• :name

For cost centers, selection writes:

• :number
• :name
• :employee when present on the selected option

Cancel Behavior

Cancelling closes the editor and restores the display view without changing data.

Error Handling And Edge Cases

• If master data for the legal entity is missing, the HTMX fragment renders a disabled empty state such as No GL accounts available or No cost centers available.
• If the current structured value is not present in master data, the editor still shows that current value as a stale selection so the user can replace it intentionally.
• If filtering returns no matches, the results list renders an explicit empty state.
• If a field is empty, the picker opens with an empty query and an initial result list.
• If multiple options share the same number, the UI renders both in source order. This is treated as a master-data quality problem, not a picker-level validation concern.

Why This Design

Why HTMX On Demand

• Fits the existing document detail architecture, which already relies on HTMX fragment swaps.
• Keeps legal-entity scoping and authorization on the server.
• Avoids increasing initial page payload for users who never edit these fields.

Why Client-Side Filtering

• Dataset size is bounded low enough to keep typing responsive.
• Avoids per-keystroke server requests and debounce complexity.
• Keeps the endpoint simple: one request to open the editor, then local filtering.

Why A Custom Combobox

• Matches the issue requirement of a single field with searchable master data.
• Supports number/name/employee search in one control.
• Avoids the UX and styling limitations of native <select> and <datalist>.

Testing Expectations

Add coverage for:

• fragment rendering for debit account, credit account, and cost center editors
• client-side filtering by number
• client-side filtering by name
• client-side filtering by employee for cost centers
• selection writing the expected structured subfields
• stale current value rendering
• empty dataset rendering

Assumptions

• Legal-entity datasets for GL accounts and cost centers remain below 500 items each.
• Existing document schema remains unchanged; only the editing surface changes.
• The combined rest-state display string is presentation-only and is derived from the structured fields.