@iyulab/lowline-form 0.10.0 → 0.12.0

package/README.md

@@ -1,7 +1,8 @@
 # `<lowline-form>`
 
 A formdown form whose decided fields are suggested from the records people confirmed, talking to a Lowline host's
-routes (`MapLowline` in .NET).
+routes — the contract at the end of this page, which a host implements over the engine (the .NET reference host is
+[`samples/aspnet`](../../samples/aspnet)).
 
 ```html
 <lowline-form src="/lowline" form="intake" record="r-17"></lowline-form>
@@ -20,6 +21,8 @@ routes (`MapLowline` in .NET).
 | `content` | The form's formdown text. |
 | `data` | The record's values when it was opened. |
 | `rate` | How often a field's answer is held back to check it, from 0 to 1 (one in twenty by default). |
+| `prefill` | Whether a suggestion the engine allows to go in unasked is put in the field before the person takes it. Off by default — a value in a field reads as the person's own. |
+| `promise-rate` | How often a suggestion's promise — right *n* times in 10 like it, rounded down — is shown beside it, from 0 to 1. Off (0) by default; the draw goes into the record, so showing it can be measured before it is turned on for everyone. |
 | `strings` | The words the form shows, in the host's language. |
 | `settled-by` | Who is writing, as an opaque id the host gives — one person, one id, never a name. Sent with the save when set. |
 | `batch` | The batch the record is written in, when several come at once from one source. Sent with the save when set. |
@@ -43,3 +46,18 @@ npm ci
 npm test
 npm run bundle   # one file with Lit and formdown inside, in dist/bundle
 ```
+
+## The routes a host serves
+
+Under the prefix the host mounted them at (`src`):
+
+| Route | Takes | Answers |
+|---|---|---|
+| `POST {form}/propose` | `{ "id", "values" }` — the record so far | per open decided field: the suggestion, what it rests on, its `promise`, or why there is none |
+| `POST {form}/settle` | `{ "id", "saved", "draft" }` — no `saved` with `Saved` | `{ "id", "settledAt" }`; 400 for a value the form cannot hold, and nothing is learned |
+| `GET {form}/report` | — | per decided field: the thresholds chosen, how many records they were chosen on (`chosenOn`), and what the replay of the records saw at them |
+| `POST {form}/fill` | `{ "values", "text", "attachments" }` — `attachments`, optional: what the person showed, each `{ "mediaType", "data" (base64), "name" }`; `text` may be empty when something is shown | the model's values as suggestions; 400 for data that is not base64; 404 saying so without a model |
+| `POST {form}/judge` | `{ "id", "values" }` | the model's judgements for the fields the records could not answer; 404 saying so without a model |
+
+A form not defined is 404. Each request's memory space and allowed choices come from the host, never from the request
+body. The shapes are the engine's own wire shapes: in .NET, `LowlineJson` serializes them.