stencila/designa

Add component for `Parameter`

Closed this issue · 0 comments

Background

The Stencila Schema includes the Parameter node type. The main use case for this type is "document parameters" - variables of an executable document that are explicitly identified, by the document's author/s, as being modifiable by readers i.e. "things that you might want to play around with to understand this document better". If that doesn't make sense, here's the obligatory reference to Brett Victor's work which elucidates the notion more fully: http://worrydream.com/ExplorableExplanations/.

(The Parameter schema is also intended to be able to be used as a "function parameter" both for storing the results of semantic code analysis but also for "calling documents", as one would call a function, with certain values (i.e. arguments) for its parameters. But that is ancillary to the scope of this issue).

We are in the process of re-implementing reactive documents in Stencila (we've had them in various incarnations in the past). We have a first iteration of dependency graph generation based on code analysis and are starting to implement cyclic, round-trip reactivity via patches, from the client to the server and back again in stencila/stencila#1155 e.g.

image

The current, temporary, HTML encoding of the parameters is simply:

<input itemtype="https://stenci.la/Parameter" itemscope="" id="par-a" type="number" name="a" value="4">

Requirements

In a nutshell, we need user interface elements to represent different types of Parameter nodes that are visually and behaviorally consistent with stencila-code-expression and stencila-code-chunk nodes.

Here different "types" of parameters means parameters having different validators. Different validator types and instances might map to different HTML <input> types. For example, a EnumValidator might map to a <select>. A NumberValidator might map to a <input type="number"> but to a <input type="range" min="0", max="100"> if both minimum and maximum (or exclusiveMinimum and exclusiveMaximum) are set.

Todo

A preliminary to do list:

  • Define semantic mappings between Parameter.validator properties and HTML elements; implement in https://github.com/stencila/stencila/blob/master/rust/src/methods/encode/html.rs
  • Consider alternative UI/UX styles for parameter widgets ranging from more explicit, native-style sliders dropdowns etc as seen in https://shiny.rstudio.com/ and more implicit, textual representations as seen in http://worrydream.com/Tangle/ (Can/ should both be possible? Should style be based on the theme?).
  • Consider what other information about the parameter needs to be readable/writable by the reader e.g. which kernel the variable should be set in (the current server-side model is that a variable has a "home" kernel / language but can be cloned in another kernel for use in another language).
  • Create stencila-parameter WebComponent to expose properties of a variable, and at the least have an executeHandler to send a patch to the server to update its value