Dynamic option sources: host-registered providers for choice fields (user picker / live registries)

[horner]

Summary

Choice fields (dropdown, radio, openchoice, multiselectdropdown) can only carry static options baked into the FormDefinition. Forms that need to offer people or other live registries — with search-as-you-type — currently have to fall back to free text.

Proposal: a declarative optionsSource on option-bearing fields, resolved at render time by a host-registered provider. eSheet ships no fetching/auth logic; the host app does.

The problem, concretely

The Chevron eCase case form (built on @esheet/* 0.0.5) needs:

• Case approver — required, "autocomplete based on list of Approvers / Clinicians" (Chevron tracker Conditional expressions should be able to contain arbitrary JavaScript #40)
• Disability manager — optional, "autocomplete based on list of Disability Managers" (tracker mieweb/ui : UI/UX Fixes for several components #42)

The user list lives in the host application (and changes daily), so it cannot be serialized into the form definition. Today both fields ship as plain text — free-typed names, typos and all — which is exactly what the tracker items reject.

A registered custom field type (#85) is the current escape hatch, but it means rebuilding the dropdown UX, keyboard handling, validation and response shape per app instead of reusing eSheet's.

Proposed shape

- id: caseApprover
  fieldType: dropdown
  question: Case approver
  required: true
  optionsSource:
    provider: users          # host-registered name
    params: { role: approver }

Host side (renderer or form store):

registerOptionsProvider('users', async (query, params) => FieldOption[]);

• Provider is called on open/typeahead with the current query; results render as normal options.
• The response stays self-contained: the chosen option is stored as the usual selected: { id, value }, so hydration/projection of old responses never needs the provider again.
• Static options and optionsSource can coexist (static entries pinned, e.g. "Unassigned").
• A definition with an unregistered provider degrades gracefully (empty list + console warning), keeping definitions portable.

Non-goals

• eSheet performing HTTP itself, auth, caching policy — all host concerns inside the provider.
• Builder UI for browsing providers (v1 can be a plain provider-name input).

Related

• Design | Feature : Observation Lookup #78 external context is the read-only expression counterpart of this; this issue is about answerable options.
• Field: Custom Field Field  #85 custom field types — the workaround this replaces for plain "pick from a live list" cases.
• New Field: Dynamic List Field (Allergy, Conditions, Meds #84 dynamic list field — repeatable entries; combines well with provider-driven suggestions.

Acceptance criteria

• A YAML/JSON definition can declare optionsSource: { provider, params? } on option-bearing fields and still validate against formDefinitionSchema.
• Host can register/unregister providers; renderer calls them with the typed query (debounced).
• Selected values persist as ordinary selected responses and survive rendering without the provider.
• Conditional rules comparing against a provider-supplied option id behave like static options.
• Docs page under fields/options describing the contract.

[redmine-bridge-mieweb]

Redmine Ticket: #158289 created from GitHub Issue