@iyulab/lowline-form 0.7.0 → 0.9.0

package/dist/draft.d.ts

@@ -8,10 +8,21 @@ export interface Suggestion {
     origin?: 'decider' | 'other';
     fit?: 'exact' | 'prefix';
 }
-interface Track {
+/** 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. */
+export interface Reported {
+    layer?: Layer | null;
+    promise?: number;
+}
+interface Track extends Reported {
     shown?: Suggestion;
     declined?: boolean;
     held?: number;
+    /** The answer held back for a check, kept so the record can say what the person was not shown. */
+    withheld?: Suggestion;
+    /** When the person reached the field, or its suggestion came into view — the first — on the session's clock, in milliseconds. */
+    at?: number;
 }
 /**
  * The account of one record while it is written: the values it was opened with, and for each field the suggestion
@@ -19,17 +30,42 @@ interface Track {
  * turns it, with the saved values, into what each decided field teaches — so a value taken from a suggestion is never
  * counted as one typed. It is only bookkeeping: nothing is counted here.
  *
- * Written as the engine reads it: `{ opened, fields: { field: { shown, declined, held } } }`.
+ * 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`.
  */
 export declare class Draft {
     readonly opened: Values;
     readonly fields: Record<string, Track>;
+    private openedAt?;
+    private savedAt?;
+    private arrival;
+    private by?;
+    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. */
-    show(field: string, suggestion: Suggestion): void;
-    /** The field's answer is held back for a check, drawn with `probability`: what the person settles is checked. */
-    hold(field: string, probability: number): void;
+    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.
+     */
+    hold(field: string, probability: number, withheld?: {
+        suggestion: Suggestion;
+    } & Reported): void;
+    /** 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. */
+    saveAt(ms: number): void;
+    /** The person reached the field, or its suggestion came into view, at `ms`. Only the first report for a field counts. */
+    reach(field: string, ms: number): void;
+    /** The field's current value arrived now: it moves to the end of the order values arrived in. */
+    arrived(field: string): void;
+    /** The record is settled by the person `id`: an opaque id, one person, one id; not a name. */
+    settledBy(id: string): void;
+    /** The record is settled in the batch `id`, with the records that came at once from the same source. */
+    inBatch(id: string): void;
+    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. */
@@ -39,6 +75,11 @@ export declare class Draft {
     toJSON(): {
         opened: Values;
         fields: Record<string, Track>;
+        opened_at?: number;
+        saved_at?: number;
+        arrival?: string[];
+        by?: string;
+        batch?: string;
     };
 }
 export declare function isEmpty(value: Value | undefined): boolean;

package/dist/draft.js

@@ -4,27 +4,79 @@
  * turns it, with the saved values, into what each decided field teaches — so a value taken from a suggestion is never
  * counted as one typed. It is only bookkeeping: nothing is counted here.
  *
- * Written as the engine reads it: `{ opened, fields: { field: { shown, declined, held } } }`.
+ * 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`.
  */
 export class Draft {
     /** A record opened holding `values` — none for a new one. Empty values are left out. */
     constructor(values = {}) {
         this.fields = {};
+        this.arrival = [];
         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. */
-    show(field, suggestion) {
+    show(field, suggestion, reported = {}) {
         const track = (this.fields[field] ??= {});
         if (!sameSuggestion(track.shown, suggestion))
             track.declined = false;
         track.shown = { ...suggestion };
         delete track.held;
+        delete track.withheld;
+        this.report(track, reported);
     }
-    /** The field's answer is held back for a check, drawn with `probability`: what the person settles is checked. */
-    hold(field, probability) {
+    /**
+     * 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.
+     */
+    hold(field, probability, withheld) {
         if (!(probability > 0 && probability <= 1))
             throw new RangeError('a check is drawn with a probability above 0 and at most 1');
-        this.fields[field] = { held: probability };
+        const at = this.fields[field]?.at;
+        const track = { held: probability };
+        if (at !== undefined)
+            track.at = at;
+        if (withheld) {
+            track.withheld = { ...withheld.suggestion };
+            this.report(track, withheld);
+        }
+        this.fields[field] = track;
+    }
+    /** 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);
+    }
+    /** The record is being saved at `ms` on the same clock. */
+    saveAt(ms) {
+        this.savedAt = whole(ms);
+    }
+    /** The person reached the field, or its suggestion came into view, at `ms`. Only the first report for a field counts. */
+    reach(field, ms) {
+        const track = (this.fields[field] ??= {});
+        track.at ??= whole(ms);
+    }
+    /** The field's current value arrived now: it moves to the end of the order values arrived in. */
+    arrived(field) {
+        this.arrival = this.arrival.filter((f) => f !== field);
+        this.arrival.push(field);
+    }
+    /** The record is settled by the person `id`: an opaque id, one person, one id; not a name. */
+    settledBy(id) {
+        this.by = id;
+    }
+    /** The record is settled in the batch `id`, with the records that came at once from the same source. */
+    inBatch(id) {
+        this.batch = id;
+    }
+    report(track, { layer, promise }) {
+        if (layer)
+            track.layer = layer;
+        else
+            delete track.layer;
+        if (promise !== undefined)
+            track.promise = promise;
+        else
+            delete track.promise;
     }
     /** The person turned down the suggestion in view; false, changing nothing, when none was shown. */
     decline(field) {
@@ -46,9 +98,21 @@ export class Draft {
         return this.fields[field]?.held;
     }
     toJSON() {
-        return { opened: this.opened, fields: this.fields };
+        return {
+            opened: this.opened,
+            fields: this.fields,
+            ...(this.openedAt !== undefined ? { opened_at: this.openedAt } : {}),
+            ...(this.savedAt !== undefined ? { saved_at: this.savedAt } : {}),
+            ...(this.arrival.length > 0 ? { arrival: this.arrival } : {}),
+            ...(this.by !== undefined ? { by: this.by } : {}),
+            ...(this.batch !== undefined ? { batch: this.batch } : {}),
+        };
     }
 }
+/** A time the engine reads: whole milliseconds, never negative. */
+function whole(ms) {
+    return Math.max(0, Math.round(ms));
+}
 function sameSuggestion(a, b) {
     return a !== undefined && a.value === b.value && (a.origin ?? 'decider') === (b.origin ?? 'decider') && (a.fit ?? 'exact') === (b.fit ?? 'exact');
 }

package/dist/lowline-form.d.ts

@@ -29,6 +29,10 @@ export declare class LowlineForm extends LitElement {
     rate: number;
     /** The words the form shows, in the host's language. */
     strings: Strings;
+    /** 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. */
+    batch: string;
     private formdown?;
     private session?;
     private asking?;

package/dist/lowline-form.js

@@ -41,11 +41,16 @@ let LowlineForm = class LowlineForm extends LitElement {
         this.rate = 0.05;
         /** The words the form shows, in the host's language. */
         this.strings = englishStrings;
+        /** 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. */
+        this.batch = '';
         this.client = new LowlineClient(this.src);
         this.fieldStates = {};
         /** Whether the host judges what the records could not answer — until its `judge` route says it has no model. */
         this.canJudge = true;
         this.changed = () => {
+            this.session?.took(this.values());
             clearTimeout(this.asking);
             this.asking = setTimeout(() => void this.ask(), ASK_DELAY_MS);
         };
@@ -114,6 +119,8 @@ let LowlineForm = class LowlineForm extends LitElement {
         if (!this.session || !this.form || !this.record)
             throw new Error('lowline-form needs a form and a record to save');
         const values = this.values();
+        this.session.took(values);
+        this.session.beforeSave(this.settledBy || undefined, this.batch || undefined);
         const saved = await this.client.settle(this.form, this.record, this.session.draft, sendValues ? values : undefined);
         this.session.saved(values);
         this.dispatchEvent(new CustomEvent('lowline-saved', { detail: { ...saved, values }, bubbles: true, composed: true }));
@@ -157,8 +164,10 @@ let LowlineForm = class LowlineForm extends LitElement {
         const formdown = this.formdown;
         if (!formdown)
             return;
-        if (Object.keys(round.prefill).length > 0)
+        if (Object.keys(round.prefill).length > 0) {
             formdown.updateData({ ...formdown.data, ...round.prefill });
+            session.took(this.values());
+        }
         formdown.fieldStates = this.fieldStates;
         if (this.canJudge)
             void this.judge(session, values, shown);
@@ -213,6 +222,12 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], LowlineForm.prototype, "strings", void 0);
+__decorate([
+    property({ attribute: 'settled-by' })
+], LowlineForm.prototype, "settledBy", void 0);
+__decorate([
+    property()
+], LowlineForm.prototype, "batch", void 0);
 __decorate([
     query('formdown-ui')
 ], LowlineForm.prototype, "formdown", void 0);

package/dist/session.d.ts

@@ -68,6 +68,8 @@ export declare class Session {
     readonly rate: number;
     private readonly random;
     private readonly strings;
+    /** A steady clock in milliseconds (`performance.now()` by default): the record's times are read from it. */
+    private readonly clock;
     draft: Draft;
     private drawn;
     /** Fields whose value the form put in unasked, from the suggestion still shown. */
@@ -76,7 +78,18 @@ export declare class Session {
     private written;
     /** The judgement asked for each field, by what it reads; `null` while the host is still judging. */
     private judgements;
-    constructor(id: string, opened: Values, rate?: number, random?: () => number, strings?: Strings);
+    /** 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, 
+    /** A steady clock in milliseconds (`performance.now()` by default): the record's times are read from it. */
+    clock?: () => number);
+    /**
+     * The form's values are `values` now: each field whose value is new since the last look arrived, and the person has
+     * reached it. A value the form put in unasked arrives too — it is when the record came to hold it.
+     */
+    took(values: Values): void;
+    /** The record is about to be saved by `by`, in `batch`: the draft says so, with the time. */
+    beforeSave(by?: string, batch?: string): void;
     /**
      * Takes a round of proposals for the form's `values` now. A field offered a value from the person's writing keeps it
      * in view until the person picks it or turns it down.

package/dist/session.js

@@ -12,11 +12,14 @@ export const englishStrings = {
  * is looked at, and only for a value the decider suggests.
  */
 export class Session {
-    constructor(id, opened, rate = 0.05, random = Math.random, strings = englishStrings) {
+    constructor(id, opened, rate = 0.05, random = Math.random, strings = englishStrings, 
+    /** A steady clock in milliseconds (`performance.now()` by default): the record's times are read from it. */
+    clock = () => performance.now()) {
         this.id = id;
         this.rate = rate;
         this.random = random;
         this.strings = strings;
+        this.clock = clock;
         this.drawn = new Set();
         /** Fields whose value the form put in unasked, from the suggestion still shown. */
         this.filled = new Set();
@@ -25,6 +28,30 @@ export class Session {
         /** The judgement asked for each field, by what it reads; `null` while the host is still judging. */
         this.judgements = new Map();
         this.draft = new Draft(opened);
+        this.draft.openAt(this.clock());
+        this.seen = { ...this.draft.opened };
+    }
+    /**
+     * The form's values are `values` now: each field whose value is new since the last look arrived, and the person has
+     * reached it. A value the form put in unasked arrives too — it is when the record came to hold it.
+     */
+    took(values) {
+        const now = this.clock();
+        for (const [field, value] of Object.entries(values)) {
+            if (isEmpty(value) || sameValue(this.seen[field], value))
+                continue;
+            this.draft.arrived(field);
+            this.draft.reach(field, now);
+        }
+        this.seen = { ...values };
+    }
+    /** The record is about to be saved by `by`, in `batch`: the draft says so, with the time. */
+    beforeSave(by, batch) {
+        this.draft.saveAt(this.clock());
+        if (by)
+            this.draft.settledBy(by);
+        if (batch)
+            this.draft.inBatch(batch);
     }
     /**
      * Takes a round of proposals for the form's `values` now. A field offered a value from the person's writing keeps it
@@ -32,9 +59,9 @@ export class Session {
      */
     apply(proposals, values) {
         const round = { fieldStates: Object.fromEntries(this.written), prefill: {} };
-        for (const { field, suggestion } of proposals) {
-            if (suggestion && !this.written.has(field))
-                this.draw(field, suggestion);
+        for (const proposal of proposals) {
+            if (proposal.suggestion && !this.written.has(proposal.field))
+                this.draw(proposal);
         }
         // A field held back for a check holds back the open fields of its group: the person settling it with nothing in view
         // is not shown what is suggested alongside it. Only the held field is the check.
@@ -49,7 +76,8 @@ export class Session {
             // Turned down, it stays down for this record: neither shown again nor put back in.
             if (this.draft.declined(field, suggestion))
                 continue;
-            this.draft.show(field, suggestion);
+            this.draft.show(field, suggestion, proposal);
+            this.draft.reach(field, this.clock());
             if (proposal.prefill && isEmpty(values[field])) {
                 round.prefill[field] = suggestion.value;
                 this.filled.add(field);
@@ -139,13 +167,18 @@ export class Session {
     /** The record was saved holding `values`: what is written next starts from them. */
     saved(values) {
         this.draft = new Draft(values);
+        this.draft.openAt(this.clock());
+        this.seen = { ...this.draft.opened };
         this.drawn.clear();
         this.filled.clear();
         this.written.clear();
         this.judgements.clear();
     }
     /** Whether the field's answer is held back now — drawn the first time a checkable value is proposed for it. */
-    draw(field, suggestion) {
+    draw(proposal) {
+        const { field, suggestion } = proposal;
+        if (!suggestion)
+            return false;
         if (this.drawn.has(field))
             return this.draft.held(field) !== undefined;
         const checkable = (suggestion.origin ?? 'decider') === 'decider' && (suggestion.fit ?? 'exact') === 'exact';
@@ -153,7 +186,7 @@ export class Session {
             return false;
         this.drawn.add(field);
         if (this.rate > 0 && this.rate <= 1 && this.random() < this.rate) {
-            this.draft.hold(field, this.rate);
+            this.draft.hold(field, this.rate, { ...proposal, suggestion });
             return true;
         }
         return false;
@@ -173,6 +206,9 @@ export class Session {
         return undefined;
     }
 }
+function sameValue(a, b) {
+    return JSON.stringify(a ?? '') === JSON.stringify(b);
+}
 /** What a proposal asking for a judgement reads, as one text. */
 function reads(proposal) {
     return JSON.stringify(proposal.asks ?? []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/lowline-form",
-  "version": "0.7.0",
+  "version": "0.9.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": {