@iyulab/lowline-form 0.10.0 → 0.12.0

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,13 +10,27 @@ 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;
+}
+/**
+ * Whether the promise of the answer shown was displayed beside it, and the probability it was drawn to be displayed with
+ * — fixed before the draw: 1 for a form that always displays it, 0 for one that never does.
+ */
+export interface PromiseShown {
+    shown: boolean;
+    probability: number;
 }
 interface Track extends Reported {
     shown?: Suggestion;
+    /** Whether the promise of the suggestion shown was displayed beside it. */
+    promise_shown?: PromiseShown;
     declined?: boolean;
     held?: number;
     /** The answer held back for a check, kept so the record can say what the person was not shown. */
@@ -32,9 +46,10 @@ 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`, `promise_shown`, `at` and `withheld`.
  */
 export declare class Draft {
+    #private;
     readonly opened: Values;
     readonly fields: Record<string, Track>;
     private openedAt?;
@@ -44,15 +59,24 @@ export declare class Draft {
     private batch?;
     /** A record opened holding `values` — none for a new one. Empty values are left out. */
     constructor(values?: Values);
-    /** A suggestion came into view for the field. A suggestion turned down earlier stays turned down only if it is this. */
+    /**
+     * A suggestion came into view for the field. It is turned down if the person turned its value down before in this
+     * record — even with other suggestions shown since.
+     */
     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;
     } & Reported): void;
+    /**
+     * Whether the promise of the suggestion shown for the field was displayed beside it, drawn with `probability` (fixed
+     * before the draw: 1 for always, 0 for never). It stands until another suggestion is shown or the answer is held back
+     * for a check. False, changing nothing, when no suggestion is shown.
+     */
+    showPromise(field: string, shown: boolean, probability: number): boolean;
     /** The record was opened at `ms` on the session's clock (a steady clock in milliseconds: only differences are read). */
     openAt(ms: number): void;
     /** The record is being saved at `ms` on the same clock. */
@@ -68,7 +92,7 @@ export declare class Draft {
     private report;
     /** The person turned down the suggestion in view; false, changing nothing, when none was shown. */
     decline(field: string): boolean;
-    /** Whether `suggestion` is the one in view for the field and the person turned it down. */
+    /** Whether `suggestion` is the one in view for the field and the person turned it down — now or before, in this record. */
     declined(field: string, suggestion: Suggestion): boolean;
     shown(field: string): Suggestion | undefined;
     held(field: string): number | undefined;

package/dist/draft.js

@@ -6,20 +6,29 @@
  *
  * 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`, `promise_shown`, `at` and `withheld`.
  */
 export class Draft {
+    /** The values the person turned down, by field: for this record, each stays turned down whatever is shown between. */
+    #turnedDown;
     /** A record opened holding `values` — none for a new one. Empty values are left out. */
     constructor(values = {}) {
         this.fields = {};
         this.arrival = [];
+        /** The values the person turned down, by field: for this record, each stays turned down whatever is shown between. */
+        this.#turnedDown = new Map();
         this.opened = Object.fromEntries(Object.entries(values).filter(([, v]) => !isEmpty(v)));
     }
-    /** A suggestion came into view for the field. A suggestion turned down earlier stays turned down only if it is this. */
+    /**
+     * A suggestion came into view for the field. It is turned down if the person turned its value down before in this
+     * record — even with other suggestions shown since.
+     */
     show(field, suggestion, reported = {}) {
         const track = (this.fields[field] ??= {});
-        if (!sameSuggestion(track.shown, suggestion))
-            track.declined = false;
+        if (!sameSuggestion(track.shown, suggestion)) {
+            track.declined = this.#turnedDown.get(field)?.has(suggestion.value) === true;
+            delete track.promise_shown;
+        }
         track.shown = { ...suggestion };
         delete track.held;
         delete track.withheld;
@@ -27,7 +36,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))
@@ -42,6 +51,21 @@ export class Draft {
         }
         this.fields[field] = track;
     }
+    /**
+     * Whether the promise of the suggestion shown for the field was displayed beside it, drawn with `probability` (fixed
+     * before the draw: 1 for always, 0 for never). It stands until another suggestion is shown or the answer is held back
+     * for a check. False, changing nothing, when no suggestion is shown.
+     */
+    showPromise(field, shown, probability) {
+        if (!(probability >= 0 && probability <= 1) || (shown ? probability === 0 : probability === 1)) {
+            throw new RangeError(`a promise ${shown ? 'shown' : 'not shown'} with probability ${probability} is not possible`);
+        }
+        const track = this.fields[field];
+        if (!track?.shown)
+            return false;
+        track.promise_shown = { shown, probability };
+        return true;
+    }
     /** The record was opened at `ms` on the session's clock (a steady clock in milliseconds: only differences are read). */
     openAt(ms) {
         this.openedAt = whole(ms);
@@ -68,7 +92,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 +101,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) {
@@ -84,9 +112,12 @@ export class Draft {
         if (!track?.shown)
             return false;
         track.declined = true;
+        const values = this.#turnedDown.get(field) ?? new Set();
+        values.add(track.shown.value);
+        this.#turnedDown.set(field, values);
         return true;
     }
-    /** Whether `suggestion` is the one in view for the field and the person turned it down. */
+    /** Whether `suggestion` is the one in view for the field and the person turned it down — now or before, in this record. */
     declined(field, suggestion) {
         const track = this.fields[field];
         return track?.declined === true && sameSuggestion(track.shown, suggestion);

package/dist/headless.d.ts

@@ -1,3 +1,3 @@
-export { Draft, valuesOf, type Suggestion, type Value, type Values } from './draft.js';
+export { Draft, valuesOf, type PromiseShown, 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';
 /**
@@ -27,8 +28,27 @@ export declare class LowlineForm extends LitElement {
     data: Record<string, unknown>;
     /** How often a field's answer is held back to check it, from 0 to 1. */
     rate: number;
+    /**
+     * The probability the host drew this record with to be settled again by a second person — an audit — from 0 (not
+     * audited, the default) to 1. Audited, the form shows none of what the first settler or the decider said: the decided
+     * fields' answers are held back with it as checks. Open the record with only the values it does not decide, and name
+     * the second person with `settled-by`.
+     */
+    audit: number;
     /** The words the form shows, in the host's language. */
     strings: Strings;
+    /**
+     * Whether a suggestion the engine allows to go in unasked is put in as the field's starting value. Off by default: a
+     * value in a field reads as the person's own, so a suggestion stays beside the field until the person takes it. A host
+     * that turns it on puts values in before anyone looks, and a value put in and saved unchanged is settled as taken.
+     */
+    prefill: boolean;
+    /**
+     * How often a suggestion's promise — how often a suggestion like it has been right, as a count out of ten — is shown
+     * beside it, from 0 to 1. Off (0) by default. Drawn once for each suggestion shown, and the draw is sent with the save,
+     * so a host can measure whether showing it helps people settle rightly before turning it on for everyone.
+     */
+    promiseRate: number;
     /** Who is writing, as an opaque id the host gives — one person, one id; not a name. Sent with the save when set. */
     settledBy: string;
     /** The batch the record is written in, when several come at once from one source. Sent with the save when set. */
@@ -61,10 +81,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

@@ -39,8 +39,27 @@ let LowlineForm = class LowlineForm extends LitElement {
         this.data = {};
         /** How often a field's answer is held back to check it, from 0 to 1. */
         this.rate = 0.05;
+        /**
+         * The probability the host drew this record with to be settled again by a second person — an audit — from 0 (not
+         * audited, the default) to 1. Audited, the form shows none of what the first settler or the decider said: the decided
+         * fields' answers are held back with it as checks. Open the record with only the values it does not decide, and name
+         * the second person with `settled-by`.
+         */
+        this.audit = 0;
         /** The words the form shows, in the host's language. */
         this.strings = englishStrings;
+        /**
+         * Whether a suggestion the engine allows to go in unasked is put in as the field's starting value. Off by default: a
+         * value in a field reads as the person's own, so a suggestion stays beside the field until the person takes it. A host
+         * that turns it on puts values in before anyone looks, and a value put in and saved unchanged is settled as taken.
+         */
+        this.prefill = false;
+        /**
+         * How often a suggestion's promise — how often a suggestion like it has been right, as a count out of ten — is shown
+         * beside it, from 0 to 1. Off (0) by default. Drawn once for each suggestion shown, and the draw is sent with the save,
+         * so a host can measure whether showing it helps people settle rightly before turning it on for everyone.
+         */
+        this.promiseRate = 0;
         /** Who is writing, as an opaque id the host gives — one person, one id; not a name. Sent with the save when set. */
         this.settledBy = '';
         /** The batch the record is written in, when several come at once from one source. Sent with the save when set. */
@@ -60,6 +79,8 @@ let LowlineForm = class LowlineForm extends LitElement {
             const formdown = this.formdown;
             if (formdown)
                 formdown.updateData({ ...formdown.data, [field]: value });
+            // A value taken is one the records can answer from: ask again, as after a value typed.
+            this.changed();
         };
         this.declined = (event) => {
             const { field } = event.detail;
@@ -80,11 +101,26 @@ let LowlineForm = class LowlineForm extends LitElement {
             this.client = new LowlineClient(this.src);
             this.canJudge = true;
         }
-        if (changed.has('record') || changed.has('form') || changed.has('data') || changed.has('content')) {
+        if (changed.has('record') ||
+            changed.has('form') ||
+            changed.has('data') ||
+            changed.has('content') ||
+            changed.has('audit')) {
             // The values it was opened with are taken before anything is suggested or put in.
             this.session = new Session(this.record, valuesOf(this.data), this.rate, Math.random, this.strings);
+            this.session.prefills = this.prefill;
+            this.session.promises = this.promiseRate;
+            this.session.audit = this.audit;
             this.fieldStates = {};
         }
+        else if (this.session) {
+            if (changed.has('prefill'))
+                this.session.prefills = this.prefill;
+            if (changed.has('promiseRate'))
+                this.session.promises = this.promiseRate;
+            if (changed.has('strings'))
+                this.session.strings = this.strings;
+        }
     }
     updated(changed) {
         if (changed.has('record') || changed.has('form') || changed.has('content'))
@@ -127,19 +163,22 @@ 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);
         if (this.formdown)
             this.formdown.fieldStates = this.fieldStates;
+        // The fields the writing did not fill keep what the records say of them.
+        void this.ask();
     }
     /** Asks again what to show for the decided fields still open. */
     async ask() {
@@ -169,7 +208,7 @@ let LowlineForm = class LowlineForm extends LitElement {
             session.took(this.values());
         }
         formdown.fieldStates = this.fieldStates;
-        if (this.canJudge)
+        if (this.canJudge && !session.auditing)
             void this.judge(session, values, shown);
     }
     /**
@@ -219,9 +258,18 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], LowlineForm.prototype, "rate", void 0);
+__decorate([
+    property({ type: Number })
+], LowlineForm.prototype, "audit", void 0);
 __decorate([
     property({ attribute: false })
 ], LowlineForm.prototype, "strings", void 0);
+__decorate([
+    property({ type: Boolean })
+], LowlineForm.prototype, "prefill", void 0);
+__decorate([
+    property({ type: Number, attribute: 'promise-rate' })
+], LowlineForm.prototype, "promiseRate", void 0);
 __decorate([
     property({ attribute: 'settled-by' })
 ], LowlineForm.prototype, "settledBy", void 0);

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;
 }
@@ -53,6 +55,18 @@ export interface Strings {
     fromJudgement: string;
     /** The note of a value filled in from what the person wrote. */
     fromWriting: string;
+    /**
+     * The note of an empty decided field shown no suggestion, by why: a field is never left looking like one that is not
+     * decided. An empty text shows no note for that reason.
+     */
+    abstain: Record<Abstain, string>;
+    /** The note of an empty decided field a judgement was asked for and gave nothing the form can show. */
+    judgedNothing: string;
+    /**
+     * How often a suggestion like the one shown has been right, as a count out of ten — `{right}` is filled in. Said only
+     * when the host turns the display on (`promises`), after where the suggestion comes from.
+     */
+    promise: string;
 }
 export declare const englishStrings: Strings;
 /** What the form does with one round of proposals: what each field shows, and the values to put in unasked. */
@@ -69,7 +83,8 @@ export declare class Session {
     readonly id: string;
     readonly rate: number;
     private readonly random;
-    private readonly strings;
+    /** The words the form shows; a host may change them while a record is written, and the next round says them. */
+    strings: Strings;
     /** A steady clock in milliseconds (`performance.now()` by default): the record's times are read from it. */
     private readonly clock;
     draft: Draft;
@@ -78,11 +93,37 @@ export declare class Session {
     private filled;
     /** What filling from the person's writing offers, by field, until the person picks it or turns it down. */
     private written;
+    /** Why filling from the person's writing gave a field nothing to offer, by field, until it offers one. */
+    private unfilled;
     /** The judgement asked for each field, by what it reads; `null` while the host is still judging. */
     private judgements;
+    /**
+     * Whether a suggestion the engine allows to go in unasked (`prefill`) is put in as the field's starting value. Off, it
+     * stays beside the field until the person takes it.
+     */
+    prefills: boolean;
+    /**
+     * How often the promise of a suggestion is shown beside it, from 0 (never — the default) to 1 (always). Drawn once for
+     * each suggestion a field shows, and the draw goes into the draft — so the records can tell whether seeing it changed
+     * what people settled. A value outside 0 to 1 shows none.
+     */
+    promises: number;
+    /**
+     * The probability this record was drawn with to be settled again by a second person — an audit — or 0 (the default)
+     * for a record written as usual. Above 0 and at most 1, the person is shown nothing the first settler or the decider
+     * said: every decided field's answer is held back with this probability (a check), and no other suggestion, note or
+     * judgement is shown. The host draws the record and opens it with only the values it did not decide.
+     */
+    audit: number;
+    /** Whether the record is being audited: `audit` is a probability above 0 and at most 1. */
+    get auditing(): boolean;
+    /** The promise draw of the suggestion each field shows: whether its promise is shown. */
+    private promised;
     /** The values the form held when it was last looked at, to tell which fields' values arrived since. */
     private seen;
-    constructor(id: string, opened: Values, rate?: number, random?: () => number, strings?: Strings, 
+    constructor(id: string, opened: Values, rate?: number, random?: () => number, 
+    /** The words the form shows; a host may change them while a record is written, and the next round says them. */
+    strings?: Strings, 
     /** A steady clock in milliseconds (`performance.now()` by default): the record's times are read from it. */
     clock?: () => number);
     /**
@@ -131,6 +172,15 @@ export declare class Session {
     saved(values: Values): void;
     /** Whether the field's answer is held back now — drawn the first time a checkable value is proposed for it. */
     private draw;
+    /** How often promises are shown: `promises` when it is one, else never. */
+    private promiseRate;
+    /** Whether the promise of the field's suggestion `value` is shown — drawn the first time that suggestion is shown. */
+    private promiseShown;
+    /**
+     * A promise as a count out of ten, rounded down: a promise is never said higher than the records bear it out, and a
+     * count reads more plainly than a percentage.
+     */
+    private promiseNote;
     /** Where the suggestion comes from, in words. A field's value is shown as the record holds it now. */
     private note;
 }