@iyulab/lowline-form 0.10.0 → 0.12.0

package/dist/session.js

@@ -3,8 +3,20 @@ export const englishStrings = {
     decline: 'Not this',
     fromValue: 'As before with {field} {value}',
     fromSimilar: 'As in a similar record',
-    fromJudgement: 'Suggested from what was written',
+    fromJudgement: 'Judged from this record’s values — no settled record answers it',
     fromWriting: 'From what you wrote',
+    abstain: {
+        off: 'Yours to decide — this form suggests nothing here',
+        'no-evidence': 'No suggestion yet — nothing settled bears on it',
+        unsure: 'No suggestion — the records are not sure enough',
+        'not-allowed': 'No suggestion among the choices you may pick',
+        'needs-judgement': 'Needs your judgement — the records cannot tell',
+        'not-a-choice': 'No suggestion — the value given was not one of the choices',
+        malformed: 'No suggestion — the value given does not fit this field',
+        together: 'No suggestion until the fields decided with it are settled',
+    },
+    judgedNothing: 'Needs your judgement — neither the records nor a judgement gave a suggestion',
+    promise: 'right {right} times in 10 like this',
 };
 /**
  * One record being written: its draft, and what its fields show. A field's answer may be held back once, at random,
@@ -12,7 +24,13 @@ 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, 
+    /** Whether the record is being audited: `audit` is a probability above 0 and at most 1. */
+    get auditing() {
+        return this.audit > 0 && this.audit <= 1;
+    }
+    constructor(id, opened, rate = 0.05, random = Math.random, 
+    /** The words the form shows; a host may change them while a record is written, and the next round says them. */
+    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;
@@ -25,8 +43,30 @@ export class Session {
         this.filled = new Set();
         /** What filling from the person's writing offers, by field, until the person picks it or turns it down. */
         this.written = new Map();
+        /** Why filling from the person's writing gave a field nothing to offer, by field, until it offers one. */
+        this.unfilled = new Map();
         /** The judgement asked for each field, by what it reads; `null` while the host is still judging. */
         this.judgements = new Map();
+        /**
+         * 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.
+         */
+        this.prefills = true;
+        /**
+         * 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.
+         */
+        this.promises = 0;
+        /**
+         * 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.
+         */
+        this.audit = 0;
+        /** The promise draw of the suggestion each field shows: whether its promise is shown. */
+        this.promised = new Map();
         this.draft = new Draft(opened);
         this.draft.openAt(this.clock());
         this.seen = { ...this.draft.opened };
@@ -63,29 +103,53 @@ export class Session {
             if (proposal.suggestion && !this.written.has(proposal.field))
                 this.draw(proposal);
         }
+        // Audited, the record shows nothing anyone said of it: answers that can be checked are held, the rest go unshown.
+        if (this.auditing)
+            return { fieldStates: {}, prefill: {} };
         // 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.
         const held = proposals.filter((p) => this.draft.held(p.field) !== undefined);
         const hidden = (p) => held.some((h) => h.field === p.field || (h.together != null && h.together === p.together));
         for (const proposal of proposals) {
             const { field, suggestion } = proposal;
-            if (!suggestion || this.written.has(field))
+            if (this.written.has(field))
                 continue;
             if (hidden(proposal))
                 continue;
-            // Turned down, it stays down for this record: neither shown again nor put back in.
-            if (this.draft.declined(field, suggestion))
+            if (!suggestion) {
+                // Why the field is empty, said beside it: silent, it would read as a field nothing is suggested for, and a
+                // person passes over it. A field that already holds a value needs no word.
+                const judged = this.judgements.get(field)?.proposal === proposal;
+                // A field that asks for a judgement on nothing yet has not been looked at: there is nothing to say of it.
+                const early = proposal.abstain === 'needs-judgement' && (proposal.asks?.length ?? 0) === 0;
+                const why = this.unfilled.get(field) ??
+                    (judged ? this.strings.judgedNothing : proposal.abstain && !early ? this.strings.abstain[proposal.abstain] : '');
+                if (why && isEmpty(values[field]))
+                    round.fieldStates[field] = { note: why };
                 continue;
+            }
+            // Turned down, it stays down for this record — whatever was suggested between: neither shown again nor put back in.
+            // The draft takes it as the suggestion in view, turned down, so the record says what was last offered.
             this.draft.show(field, suggestion, proposal);
+            if (this.draft.declined(field, suggestion))
+                continue;
+            // The answers that carry a promise say in the record whether it was shown beside them, and with what chance.
+            const promised = proposal.promise !== undefined && (suggestion.origin ?? 'decider') === 'decider';
+            const shown = promised && this.promiseShown(field, suggestion.value);
+            if (promised)
+                this.draft.showPromise(field, shown, this.promiseRate());
             this.draft.reach(field, this.clock());
-            if (proposal.prefill && isEmpty(values[field])) {
+            if (this.prefills && proposal.prefill && isEmpty(values[field])) {
                 round.prefill[field] = suggestion.value;
                 this.filled.add(field);
             }
+            const note = [this.note(proposal, values), shown ? this.promiseNote(proposal.promise) : undefined]
+                .filter((part) => part)
+                .join(' · ');
             round.fieldStates[field] = {
                 suggestions: [suggestion.value],
                 decline: this.strings.decline,
-                ...(this.note(proposal, values) ? { note: this.note(proposal, values) } : {}),
+                ...(note ? { note } : {}),
             };
         }
         return round;
@@ -138,14 +202,21 @@ export class Session {
      * on its own, in place of what the records suggest for the field. Answers what every field shows now.
      */
     applyFill(proposals) {
-        for (const { field, suggestion } of proposals) {
-            if (!suggestion)
+        for (const { field, suggestion, abstain } of proposals) {
+            if (!suggestion) {
+                // A value was given for the field that it cannot take: said beside the field, not dropped in silence.
+                const why = abstain ? this.strings.abstain[abstain] : '';
+                if (why)
+                    this.unfilled.set(field, why);
                 continue;
+            }
+            this.unfilled.delete(field);
             this.draft.show(field, suggestion);
             this.filled.delete(field);
             this.written.set(field, { suggestions: [suggestion.value], decline: this.strings.decline, note: this.strings.fromWriting });
         }
-        return Object.fromEntries(this.written);
+        const unfilled = [...this.unfilled].filter(([field]) => !this.written.has(field));
+        return { ...Object.fromEntries(this.written), ...Object.fromEntries(unfilled.map(([field, note]) => [field, { note }])) };
     }
     /** The person picked a field's offered value: what was offered from their writing has done its part. */
     picked(field) {
@@ -170,6 +241,7 @@ export class Session {
         this.draft.openAt(this.clock());
         this.seen = { ...this.draft.opened };
         this.drawn.clear();
+        this.promised.clear();
         this.filled.clear();
         this.written.clear();
         this.judgements.clear();
@@ -185,12 +257,38 @@ export class Session {
         if (!checkable)
             return false;
         this.drawn.add(field);
+        if (this.auditing) {
+            this.draft.hold(field, this.audit, { ...proposal, suggestion });
+            return true;
+        }
         if (this.rate > 0 && this.rate <= 1 && this.random() < this.rate) {
             this.draft.hold(field, this.rate, { ...proposal, suggestion });
             return true;
         }
         return false;
     }
+    /** How often promises are shown: `promises` when it is one, else never. */
+    promiseRate() {
+        return this.promises >= 0 && this.promises <= 1 ? this.promises : 0;
+    }
+    /** Whether the promise of the field's suggestion `value` is shown — drawn the first time that suggestion is shown. */
+    promiseShown(field, value) {
+        const drawn = this.promised.get(field);
+        if (drawn?.value === value)
+            return drawn.shown;
+        const rate = this.promiseRate();
+        const shown = rate >= 1 || (rate > 0 && this.random() < rate);
+        this.promised.set(field, { value, shown });
+        return shown;
+    }
+    /**
+     * 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.
+     */
+    promiseNote(promise) {
+        const right = Math.max(0, Math.min(10, Math.floor(promise * 10 + 1e-9)));
+        return this.strings.promise.replace('{right}', String(right));
+    }
     /** Where the suggestion comes from, in words. A field's value is shown as the record holds it now. */
     note(proposal, values) {
         const first = proposal.basis?.[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/lowline-form",
-  "version": "0.10.0",
+  "version": "0.12.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": {
@@ -40,12 +40,12 @@
     "bundle": "vite build --config vite.bundle.config.ts"
   },
   "dependencies": {
-    "@formdown/ui": "^0.26.0",
+    "@formdown/ui": "^0.26.1",
     "lit": "^3.3.3"
   },
   "devDependencies": {
-    "typescript": "^6.0.3",
-    "vite": "^8.3.1",
-    "vitest": "^5.0.2"
+    "typescript": "^7.0.2",
+    "vite": "^8.3.6",
+    "vitest": "^5.1.0"
   }
 }