getodk / getodk/web-forms

Engine/Client interface: the next iteration

Open
#73 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
38
Forks
22
PR merge metrics
No merged PRs in 30d

Description

I'm opening this issue in anticipation that, following #67 and #69, we'll further iterate on the interface between `xforms-engine` and its various clients (`scenario`, `ui-vue`, `ui-solid`, hypothetical future others). Some of this iteration will likely support refinement and resolution of current features in progress (selects in particular). We'll also surely expand the interface to support the full scope of data types, field appearances, and so on. While it's highly unlikely we'll cover all of these in a single pass, it's good to have a general sense of the paths we might take in their direction.

To kick it off, below captures some thoughts on these topics (lightly edited after brain dumping the same general thoughts on Slack earlier). This isn't intended to fully frame the topic, but as a potential starting point for discussion.

- - -

In discussion around #67, the possibility of splitting up `SelectField` (and potentially `SelectNode` with it) came up. Exploratory prototyping around this, as well as adjacent exploration of `StringNode` subtypes (i.e. whether the node is model-only or has an `input`), led me to rethinki some of my instincts about upcoming changes to the client interface.

At a client level I found it much simpler, and much more obvious to consume a _greater number of distinct node types_ (even if some of them shared a lot of the same structure) rather than fewer types with sub-structural variation. This is type/subtype distinction is currently[^1] represented in #67 as `nodeType` (which narrows between top level `*Node` interfaces) + `nodeVariant` (which I had deferred for a subsequent commit, but envisioned using to narrow variations within the same node type).

For the current feature set, that would look like splitting `SelectNode` into single-value and multi-value interfaces (corresponding to `select1` and `select` XForms elements respectively). It would also look like splitting `StringNode` into `model`-only and `input` interfaces, with that distinction (which clients are already concerned with), plus the additional distinction that it doesn't really make sense for a `model`-only node to have value setters. I expect the same distinctions will play out for other data types (especially those also associated with `input`)—and I expect that we'll probably see one or more corresponding naming conventions emerge naturally as a result.

In all this, I also realized that I'm increasingly doubtful that each node type's `definition` has much value to clients _at all_. More specifically, if we were to surface the meaningful sub-type distinctions within a given `definition` as distinct node types, I doubt that a node's `definition` would have much additional value. Where there _is remaining value_ beyond type/subtype distinction, it's generally places where there are other specific gaps in the client interface. (For instance, we somehow neglected to include a form's title in this first pass on the interface!)

It's worth noting that when I began this exploratory prototyping session, I went into it with a fairly strong aversion to proliferating additional distinct node types. I had been strongly inclined to keep the set of distinct node types minimal, leaning heavily into sub-type distinctions all the way out to clients. But the actual prototyping effort made it difficult for me to justify this aversion, in the face of client code which became significantly simpler both to author, and to reason about after the fact.

[^1]: At time of writing. I intend to roll part of this back before that PR is merged.

- - -

In this discussion, @lognaturel also asked the obvious question about how this thinking might apply to `appearance`s. My instinct today is that I'm reluctant to extrapolate an opinion on that from the above findings, without a dedicated design discussion around the specific appearances we intend to support, and the implications that come from those. We might find that some `appearance` cases nudge us in a similar direction of data model expansion, and we might also find that some are purely a presentational concern. I expect that those patterns will become more clear with such a dedicated design discussion.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the context in #67 and #69, then review the current interface between xforms-engine and the scenario, ui-vue, and ui-solid clients. This issue is a broad design discussion rather than a defined change: a contributor would need an agreed direction, concrete scope, and acceptance criteria before implementation can be considered done.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.