@iyulab/lowline-form 0.10.0 → 0.11.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>
@@ -43,3 +44,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.

package/dist/bundle/lowline-form.bundle.js

@@ -31,8 +31,8 @@ var e = class {
 	inBatch(e) {
 		this.batch = e;
 	}
-	report(e, { layer: t, promise: n }) {
-		t ? e.layer = t : delete e.layer, n === void 0 ? delete e.promise : e.promise = n;
+	report(e, { layer: t, promise: n, score: r }) {
+		t ? e.layer = t : delete e.layer, n === void 0 ? delete e.promise : e.promise = n, r === void 0 ? delete e.score : e.score = r;
 	}
 	decline(e) {
 		let t = this.fields[e];
@@ -207,8 +207,12 @@ var l = class extends Error {
 			draft: n
 		});
 	}
-	fill(e, t, n) {
-		return this.post(e, "fill", {
+	fill(e, t, n, r) {
+		return this.post(e, "fill", r?.length ? {
+			values: t,
+			text: n,
+			attachments: r
+		} : {
 			values: t,
 			text: n
 		});
@@ -11274,11 +11278,11 @@ var zl = 300, $ = class extends Je {
 			composed: !0
 		})), n;
 	}
-	async fill(e) {
-		let t = this.session;
-		if (!t || !this.form) return;
-		let n = await this.client.fill(this.form, this.values(), e);
-		t === this.session && (this.fieldStates = t.applyFill(n), this.formdown && (this.formdown.fieldStates = this.fieldStates));
+	async fill(e, t) {
+		let n = this.session;
+		if (!n || !this.form) return;
+		let r = await this.client.fill(this.form, this.values(), e, t);
+		n === this.session && (this.fieldStates = n.applyFill(r), this.formdown && (this.formdown.fieldStates = this.fieldStates));
 	}
 	async ask() {
 		let e = this.session;

package/dist/client.d.ts

@@ -5,6 +5,14 @@ export declare class LowlineError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/** Something a person showed rather than wrote — a photo, a scan — sent to the host's model with a fill request. */
+export interface Attachment {
+    /** Its media type, such as `image/jpeg` or `application/pdf`. */
+    mediaType: string;
+    /** Its bytes, base64. */
+    data: string;
+    name?: string;
+}
 /** A threshold chosen on a replay of the settled records, and what the replay saw at it. */
 export interface ThresholdChoice {
     threshold: number;
@@ -43,6 +51,12 @@ export interface FieldReport {
     coarseSimilar?: ThresholdChoice;
     similar?: ThresholdChoice;
     similarOffered: boolean;
+    /**
+     * For a judgement from outside the records: the score from which it is trusted, chosen from the cases it answered and
+     * people settled (its `promise` is the precision to expect of the next answers at or above it); absent while too few
+     * cases are settled for one to stand.
+     */
+    judgement?: ThresholdChoice;
     promiseOver: number;
     /** How many checks — answers held back while a person wrote the value — are among the records. */
     checks: number;
@@ -68,8 +82,11 @@ export declare class LowlineClient {
         id: string;
         settledAt: string;
     }>;
-    /** What the host's model makes of `text` for the fields of record values still empty — 404 when the host gave none. */
-    fill(form: string, values: Values, text: string): Promise<Proposal[]>;
+    /**
+     * What the host's model makes of `text` and of what the person showed (`attachments`) for the fields of record values
+     * still empty — 404 when the host gave no model.
+     */
+    fill(form: string, values: Values, text: string, attachments?: Attachment[]): Promise<Proposal[]>;
     /**
      * What the host's model judged for the decided fields of record `id` the records could not answer
      * (`needs-judgement`) — 404 when the host gave no model.

package/dist/client.js

@@ -27,9 +27,12 @@ export class LowlineClient {
     settle(form, id, draft, saved) {
         return this.post(form, 'settle', { id, saved, draft });
     }
-    /** What the host's model makes of `text` for the fields of record values still empty — 404 when the host gave none. */
-    fill(form, values, text) {
-        return this.post(form, 'fill', { values, text });
+    /**
+     * What the host's model makes of `text` and of what the person showed (`attachments`) for the fields of record values
+     * still empty — 404 when the host gave no model.
+     */
+    fill(form, values, text, attachments) {
+        return this.post(form, 'fill', attachments?.length ? { values, text, attachments } : { values, text });
     }
     /**
      * What the host's model judged for the decided fields of record `id` the records could not answer

package/dist/draft.d.ts

@@ -10,10 +10,14 @@ export interface Suggestion {
 }
 /** The layer of the decider an answer came from. */
 export type Layer = 'key' | 'similar' | 'judgement';
-/** What the host knows of the answer it shows or holds back, beyond its value: the layer that gave it and what it promised. */
+/**
+ * What the host knows of the answer it shows or holds back, beyond its value: the layer that gave it, what it promised,
+ * and — for a judgement from outside the records — the score it gave it on its own scale.
+ */
 export interface Reported {
     layer?: Layer | null;
     promise?: number;
+    score?: number;
 }
 interface Track extends Reported {
     shown?: Suggestion;
@@ -32,7 +36,7 @@ interface Track extends Reported {
  *
  * Written as the engine reads it: `{ opened, fields: { field: { shown, declined, held } } }`, and — only what was
  * reported — `opened_at`, `saved_at` (milliseconds on one steady clock), `arrival` (the fields in the order their values
- * arrived), `by` and `batch`, and in a field `layer`, `promise`, `at` and `withheld`.
+ * arrived), `by` and `batch`, and in a field `layer`, `promise`, `score`, `at` and `withheld`.
  */
 export declare class Draft {
     readonly opened: Values;
@@ -48,7 +52,7 @@ export declare class Draft {
     show(field: string, suggestion: Suggestion, reported?: Reported): void;
     /**
      * The field's answer is held back for a check, drawn with `probability`: what the person settles is checked.
-     * `withheld` is the answer not shown, with its layer and promise, for the record to say what was held back.
+     * `withheld` is the answer not shown, with its layer, promise and score, for the record to say what was held back.
      */
     hold(field: string, probability: number, withheld?: {
         suggestion: Suggestion;

package/dist/draft.js

@@ -6,7 +6,7 @@
  *
  * Written as the engine reads it: `{ opened, fields: { field: { shown, declined, held } } }`, and — only what was
  * reported — `opened_at`, `saved_at` (milliseconds on one steady clock), `arrival` (the fields in the order their values
- * arrived), `by` and `batch`, and in a field `layer`, `promise`, `at` and `withheld`.
+ * arrived), `by` and `batch`, and in a field `layer`, `promise`, `score`, `at` and `withheld`.
  */
 export class Draft {
     /** A record opened holding `values` — none for a new one. Empty values are left out. */
@@ -27,7 +27,7 @@ export class Draft {
     }
     /**
      * The field's answer is held back for a check, drawn with `probability`: what the person settles is checked.
-     * `withheld` is the answer not shown, with its layer and promise, for the record to say what was held back.
+     * `withheld` is the answer not shown, with its layer, promise and score, for the record to say what was held back.
      */
     hold(field, probability, withheld) {
         if (!(probability > 0 && probability <= 1))
@@ -68,7 +68,7 @@ export class Draft {
     inBatch(id) {
         this.batch = id;
     }
-    report(track, { layer, promise }) {
+    report(track, { layer, promise, score }) {
         if (layer)
             track.layer = layer;
         else
@@ -77,6 +77,10 @@ export class Draft {
             track.promise = promise;
         else
             delete track.promise;
+        if (score !== undefined)
+            track.score = score;
+        else
+            delete track.score;
     }
     /** The person turned down the suggestion in view; false, changing nothing, when none was shown. */
     decline(field) {

package/dist/headless.d.ts

@@ -1,3 +1,3 @@
 export { Draft, valuesOf, type Suggestion, type Value, type Values } from './draft.js';
 export { Session, englishStrings, type Abstain, type Basis, type FieldState, type Proposal, type Round, type Strings } from './session.js';
-export { LowlineClient, LowlineError, type FieldReport, type ThresholdChoice } from './client.js';
+export { LowlineClient, LowlineError, type Attachment, type FieldReport, type ThresholdChoice } from './client.js';

package/dist/lowline-form.d.ts

@@ -1,5 +1,6 @@
 import { LitElement } from 'lit';
 import '@formdown/ui';
+import { type Attachment } from './client.js';
 import { type Values } from './draft.js';
 import { type Strings } from './session.js';
 /**
@@ -61,10 +62,11 @@ export declare class LowlineForm extends LitElement {
     }>;
     private settleWith;
     /**
-     * Fills the record from `text` — what the person wrote or a picture's description — through the host's model: each
-     * value it gives is offered in its field for the person to take. Nothing is put in on its own.
+     * Fills the record from `text` — what the person wrote — and `attachments` — what they showed: a photo, a scan —
+     * through the host's model: each value it gives is offered in its field for the person to take. Nothing is put in
+     * on its own.
      */
-    fill(text: string): Promise<void>;
+    fill(text: string, attachments?: Attachment[]): Promise<void>;
     /** Asks again what to show for the decided fields still open. */
     ask(): Promise<void>;
     /**

package/dist/lowline-form.js

@@ -127,14 +127,15 @@ let LowlineForm = class LowlineForm extends LitElement {
         return saved;
     }
     /**
-     * Fills the record from `text` — what the person wrote or a picture's description — through the host's model: each
-     * value it gives is offered in its field for the person to take. Nothing is put in on its own.
+     * Fills the record from `text` — what the person wrote — and `attachments` — what they showed: a photo, a scan —
+     * through the host's model: each value it gives is offered in its field for the person to take. Nothing is put in
+     * on its own.
      */
-    async fill(text) {
+    async fill(text, attachments) {
         const session = this.session;
         if (!session || !this.form)
             return;
-        const proposals = await this.client.fill(this.form, this.values(), text);
+        const proposals = await this.client.fill(this.form, this.values(), text, attachments);
         if (session !== this.session)
             return;
         this.fieldStates = session.applyFill(proposals);

package/dist/session.d.ts

@@ -27,10 +27,12 @@ export interface Proposal {
     together?: string | null;
     /**
      * How often an answer of this kind for this field has been right — the replay's precision at the threshold the
-     * suggestion was held to. Absent with no suggestion, for a judgement or a value from elsewhere, and before thresholds
-     * were chosen.
+     * suggestion was held to. Absent with no suggestion, for a value from elsewhere, for a judgement until the score it
+     * is trusted from was chosen from the records, and before thresholds were chosen.
      */
     promise?: number;
+    /** For a judgement from outside the records: the score it gave the suggestion, on its own scale. The draft keeps it. */
+    score?: number;
     /** Whether the field takes several values: it is settled as a set, which cannot be a check, so none is drawn for it. */
     several?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/lowline-form",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "The Lowline form element: a formdown form whose decided fields are suggested from the records people confirmed, talking to a Lowline host's routes.",
   "license": "MIT",
   "repository": {