@20baht/engine 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,3 +1,4 @@
1
+ import { type Locale } from '../i18n.js';
1
2
  import type { DerivedFieldState, FieldDescriptor, FormDefinition, Registry, ScriptContext, ScriptMessage, ValidationError } from '../types.js';
2
3
  import { type ScriptFieldState, type ScriptSink } from './scripts.js';
3
4
  /** What the host owns and hands to every step. */
@@ -13,6 +14,11 @@ export interface FormInput {
13
14
  view?: string | undefined;
14
15
  /** When errors are checked again: on every edit once some show (default), on blur, or only on validate. */
15
16
  validateOn?: 'change' | 'blur' | 'submit' | undefined;
17
+ /**
18
+ * The locale of this session's messages (validator errors, `scriptBlocked`). Unset: the
19
+ * engine's catalog as it is (`setLocale`). Two sessions in two locales can run side by side.
20
+ */
21
+ locale?: Locale | undefined;
16
22
  }
17
23
  export interface FormState {
18
24
  /** What was entered over `value`, by key. */
@@ -1,5 +1,5 @@
1
1
  import { defaultValue } from '../defaults.js';
2
- import { t } from '../i18n.js';
2
+ import { t, withLocale } from '../i18n.js';
3
3
  import { sameData } from '../same-data.js';
4
4
  import { validateField } from '../validators.js';
5
5
  import { resolveViewFields } from '../views.js';
@@ -273,6 +273,9 @@ class Step {
273
273
  }
274
274
  }
275
275
  export function updateForm(input, state, msg, host = {}) {
276
+ return withLocale(input.locale, () => runStep(input, state, msg, host));
277
+ }
278
+ function runStep(input, state, msg, host) {
276
279
  const step = new Step(input, state, host);
277
280
  switch (msg.type) {
278
281
  case 'input':
@@ -2,6 +2,8 @@ import type { ApprovalDecision, Derived, NestedData, ValidationError, WorkflowDe
2
2
  export type StepDirection = 'forward' | 'back';
3
3
  /** A run: where it stands and what it holds. Plain data, safe to keep, compare and log. */
4
4
  export interface WorkflowState {
5
+ /** The `workflow_id` of the definition the run began under. */
6
+ workflow_id: string;
5
7
  /** `evaluate()` of the run's data. `derived.data` is the data: cleared and computed values included. */
6
8
  derived: Derived;
7
9
  /** `form_name` of the step showing, or `null` when no form is visible. */
@@ -12,15 +14,27 @@ export interface WorkflowState {
12
14
  approvalError: 'commentRequired' | null;
13
15
  /** Which way the last navigation went; `null` before the first. */
14
16
  direction: StepDirection | null;
17
+ /**
18
+ * How the run ended: `'completed'` once it submitted, `'rejected'` once a rejection ended it.
19
+ * An ended run takes no more presses, decisions or navigation (a second click submits nothing);
20
+ * `start` or `restore` begins again. `null` while it runs.
21
+ */
22
+ ended: WorkflowEnd | null;
15
23
  }
24
+ export type WorkflowEnd = 'completed' | 'rejected';
16
25
  /**
17
26
  * A run as JSON: what to keep to pick it up again later (another page load, another device)
18
27
  * or to step back to (undo). The rules are not in it: `restore` runs them on `data` again.
28
+ * A copy: changing it (dropping a password before it is stored) leaves the run alone. It holds
29
+ * every value entered, `password` fields included; redact what must not be kept.
19
30
  */
20
31
  export interface WorkflowSnapshot {
32
+ /** The workflow it was taken from: `restore` under another one starts an empty run. */
33
+ workflow_id: string;
21
34
  data: NestedData;
22
35
  current: string | null;
23
36
  history: string[];
37
+ ended: WorkflowEnd | null;
24
38
  }
25
39
  interface Validity {
26
40
  valid: boolean;
@@ -65,10 +79,15 @@ export type WorkflowMsg =
65
79
  validity: Validity;
66
80
  gate: boolean;
67
81
  }
68
- /** Approve or reject the approval step showing. */
82
+ /**
83
+ * Approve or reject the approval step showing. `validity` is that of the step's own fields,
84
+ * when it has any; with `gate`, invalid ones keep the decision from being taken.
85
+ */
69
86
  | {
70
87
  type: 'decide';
71
88
  decision: ApprovalDecision;
89
+ validity?: Validity;
90
+ gate?: boolean;
72
91
  } | {
73
92
  type: 'back';
74
93
  } | {
@@ -77,7 +96,8 @@ export type WorkflowMsg =
77
96
  /**
78
97
  * Pick a kept run up again. The snapshot is untrusted (it was stored somewhere): the rules run
79
98
  * on its data, a step that is not visible falls back to the first one that is, and history
80
- * entries that are not visible steps are dropped. Navigation events are not emitted.
99
+ * entries that are not visible steps are dropped; a snapshot of another workflow restores as an
100
+ * empty run. Navigation events are not emitted.
81
101
  */
82
102
  | {
83
103
  type: 'restore';
@@ -105,7 +125,8 @@ export interface WorkflowEventMap {
105
125
  'baht-nav-blocked': {
106
126
  form_name: string | null;
107
127
  target: string;
108
- reason: 'self-transition' | 'target-hidden';
128
+ /** `rule-error`: the last step would submit data whose rules never settled (the server refuses it). */
129
+ reason: 'self-transition' | 'target-hidden' | 'rule-error';
109
130
  data: NestedData;
110
131
  };
111
132
  'baht-submit': {
@@ -41,6 +41,8 @@ export function replayWorkflow(workflow, msgs, from = null) {
41
41
  };
42
42
  }
43
43
  function step(workflow, state, msg, emit) {
44
+ if (state.ended && ENDED_IGNORES.has(msg.type))
45
+ return state;
44
46
  switch (msg.type) {
45
47
  case 'flags':
46
48
  return onVisibleStep(workflow, withData(workflow, state, state.derived.data, emit));
@@ -53,38 +55,59 @@ function step(workflow, state, msg, emit) {
53
55
  case 'next':
54
56
  return next(workflow, state, msg.validity, msg.gate, emit);
55
57
  case 'decide':
58
+ if (msg.gate && msg.validity && !msg.validity.valid)
59
+ return state;
56
60
  return decide(workflow, state, msg.decision, emit);
57
61
  case 'back':
58
62
  return back(workflow, state, emit);
59
63
  case 'gotoStart':
60
64
  return gotoStart(workflow, state, emit);
65
+ default:
66
+ return state;
61
67
  }
62
68
  }
69
+ const ENDED_IGNORES = new Set([
70
+ 'next',
71
+ 'decide',
72
+ 'back',
73
+ 'gotoStart',
74
+ ]);
63
75
  function start(workflow, previous, value, emit) {
64
76
  const derived = evaluated(workflow, structuredClone(value), previous?.derived.errors, emit);
65
77
  return {
78
+ workflow_id: workflow.workflow_id,
66
79
  derived,
67
80
  current: visibleForms(workflow, derived)[0]?.form_name ?? null,
68
81
  history: [],
69
82
  approvalError: null,
70
83
  direction: previous?.direction ?? null,
84
+ ended: null,
71
85
  };
72
86
  }
73
87
  export function snapshotOf(state) {
74
- return { data: state.derived.data, current: state.current, history: [...state.history] };
88
+ return {
89
+ workflow_id: state.workflow_id,
90
+ data: structuredClone(state.derived.data),
91
+ current: state.current,
92
+ history: [...state.history],
93
+ ended: state.ended,
94
+ };
75
95
  }
76
96
  const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
77
97
  function restore(workflow, previous, snapshot, emit) {
78
- const kept = isRecord(snapshot) ? snapshot : {};
98
+ const record = isRecord(snapshot) ? snapshot : {};
99
+ const foreign = typeof record.workflow_id === 'string' && record.workflow_id !== workflow.workflow_id;
100
+ const kept = foreign ? {} : record;
79
101
  const data = isRecord(kept.data) ? kept.data : {};
80
102
  const begun = start(workflow, previous, data, emit);
103
+ const ended = kept.ended === 'completed' || kept.ended === 'rejected' ? kept.ended : null;
81
104
  const visible = new Set(visibleForms(workflow, begun.derived).map((f) => f.form_name));
82
105
  const current = typeof kept.current === 'string' && visible.has(kept.current) ? kept.current : null;
83
106
  if (current === null)
84
- return { ...begun, direction: null };
107
+ return { ...begun, direction: null, ended };
85
108
  const walked = Array.isArray(kept.history) ? kept.history : [];
86
109
  const history = walked.filter((name) => typeof name === 'string' && name !== current && visible.has(name));
87
- return { ...begun, current, history, direction: null };
110
+ return { ...begun, current, history, direction: null, ended };
88
111
  }
89
112
  function evaluated(workflow, data, before, emit) {
90
113
  const derived = evaluate(workflow, data);
@@ -106,7 +129,7 @@ function merged(data, form_name, patch) {
106
129
  return { ...data, [form_name]: { ...data[form_name], ...patch } };
107
130
  }
108
131
  function write(workflow, state, form_name, patch, emit) {
109
- const data = merged(state.derived.data, form_name, patch);
132
+ const data = merged(state.derived.data, form_name, structuredClone(patch));
110
133
  const after = onVisibleStep(workflow, withData(workflow, state, data, emit));
111
134
  emit({ name: 'baht-data-change', detail: { data: after.derived.data } });
112
135
  return after;
@@ -132,9 +155,16 @@ function advance(workflow, state, extra, emit) {
132
155
  const data = state.derived.data;
133
156
  const targetName = nextTarget(workflow, state);
134
157
  if (targetName === 'end') {
158
+ if (state.derived.errors.some((e) => e.kind === 'data')) {
159
+ emit({
160
+ name: 'baht-nav-blocked',
161
+ detail: { form_name: state.current, target: 'end', reason: 'rule-error', data },
162
+ });
163
+ return state;
164
+ }
135
165
  emit({ name: 'baht-submit', detail: { ...extra, data } });
136
166
  emit({ name: 'baht-complete', detail: { data, status: 'completed' } });
137
- return state;
167
+ return { ...state, ended: 'completed' };
138
168
  }
139
169
  const target = visibleForms(workflow, state.derived).find((f) => f.form_name === targetName);
140
170
  if (!target || target.form_name === state.current || state.current === null) {
@@ -154,9 +184,10 @@ function advance(workflow, state, extra, emit) {
154
184
  detail: { form_name: target.form_name, order: target.order, ...extra, data },
155
185
  });
156
186
  emit(stepChange(target.form_name, target.order, 'forward'));
187
+ const seen = state.history.indexOf(target.form_name);
157
188
  return {
158
189
  ...state,
159
- history: [...state.history, state.current],
190
+ history: seen >= 0 ? state.history.slice(0, seen) : [...state.history, state.current],
160
191
  current: target.form_name,
161
192
  direction: 'forward',
162
193
  };
@@ -199,7 +230,7 @@ function decide(workflow, state, decision, emit) {
199
230
  return gotoForm(workflow, decided, onReject.form, emit);
200
231
  }
201
232
  emit({ name: 'baht-complete', detail: { data: decided.derived.data, status: 'rejected' } });
202
- return decided;
233
+ return { ...decided, ended: 'rejected' };
203
234
  }
204
235
  function gotoForm(workflow, state, form_name, emit) {
205
236
  const idx = state.history.indexOf(form_name);
package/dist/i18n.d.ts CHANGED
@@ -167,5 +167,11 @@ export declare function setLocale(locale: Locale, overrides?: Partial<MessageCat
167
167
  export declare function getCatalog(): MessageCatalog;
168
168
  /** Restore a catalog snapshot taken with getCatalog(). */
169
169
  export declare function setCatalog(catalog: MessageCatalog): void;
170
+ /**
171
+ * Run `fn` with the catalog switched to `locale`, the previous catalog put back after (also when
172
+ * it throws). The catalog is module-global; `fn` is synchronous, so two requests or two form
173
+ * sessions in different locales never see each other's. Unset: `fn` runs in the catalog as it is.
174
+ */
175
+ export declare function withLocale<T>(locale: Locale | undefined, fn: () => T): T;
170
176
  /** Resolve one catalog string, interpolating `{param}` placeholders. */
171
177
  export declare function t(key: MessageKey, params?: Record<string, unknown>): string;
package/dist/i18n.js CHANGED
@@ -287,6 +287,18 @@ export function getCatalog() {
287
287
  export function setCatalog(catalog) {
288
288
  current = catalog;
289
289
  }
290
+ export function withLocale(locale, fn) {
291
+ if (locale === undefined)
292
+ return fn();
293
+ const prev = current;
294
+ setLocale(locale);
295
+ try {
296
+ return fn();
297
+ }
298
+ finally {
299
+ current = prev;
300
+ }
301
+ }
290
302
  export function t(key, params) {
291
303
  let out = current[key] ?? en[key];
292
304
  if (params) {
package/dist/index.d.ts CHANGED
@@ -8,11 +8,11 @@ export { isSafeUrl } from './urls.js';
8
8
  export { UNSAFE_KEYS, rowSubFields } from './keys.js';
9
9
  export { resolveViewFields } from './views.js';
10
10
  export { applyFlags, flagEnabled } from './flags.js';
11
- export { getCatalog, setCatalog, setLocale, t } from './i18n.js';
11
+ export { getCatalog, setCatalog, setLocale, t, withLocale } from './i18n.js';
12
12
  export type { Locale, MessageCatalog, MessageKey } from './i18n.js';
13
13
  export { evaluate } from './engine/evaluate.js';
14
14
  export { resolveNext, stepFieldStates, visibleForms, walkPath } from './engine/graph.js';
15
- export { currentForm, nextTarget, replayWorkflow, snapshotOf, updateWorkflow, type StepDirection, type WorkflowEvent, type WorkflowEventMap, type WorkflowMsg, type WorkflowSnapshot, type WorkflowState, type WorkflowTransition, type WorkflowUpdate, } from './engine/runtime.js';
15
+ export { currentForm, nextTarget, replayWorkflow, snapshotOf, updateWorkflow, type StepDirection, type WorkflowEnd, type WorkflowEvent, type WorkflowEventMap, type WorkflowMsg, type WorkflowSnapshot, type WorkflowState, type WorkflowTransition, type WorkflowUpdate, } from './engine/runtime.js';
16
16
  export { emptyFormState, formData, formFieldState, submitScriptErrors, updateForm, validateShownField, type FormEvent, type FormEventMap, type FormHost, type FormInput, type FormMsg, type FormState, type FormUpdate, } from './engine/form-session.js';
17
17
  export { sameData } from './same-data.js';
18
18
  export { conditionRowRefs, evalCondition, parseRowRef, readRef } from './engine/conditions.js';
package/dist/index.js CHANGED
@@ -8,7 +8,7 @@ export { isSafeUrl } from './urls.js';
8
8
  export { UNSAFE_KEYS, rowSubFields } from './keys.js';
9
9
  export { resolveViewFields } from './views.js';
10
10
  export { applyFlags, flagEnabled } from './flags.js';
11
- export { getCatalog, setCatalog, setLocale, t } from './i18n.js';
11
+ export { getCatalog, setCatalog, setLocale, t, withLocale } from './i18n.js';
12
12
  export { evaluate } from './engine/evaluate.js';
13
13
  export { resolveNext, stepFieldStates, visibleForms, walkPath } from './engine/graph.js';
14
14
  export { currentForm, nextTarget, replayWorkflow, snapshotOf, updateWorkflow, } from './engine/runtime.js';
package/package.json CHANGED
@@ -1,7 +1,10 @@
1
1
  {
2
2
  "name": "@20baht/engine",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "type": "module",
5
+ "engines": {
6
+ "node": ">=20.19.0"
7
+ },
5
8
  "description": "The headless half of bahtui: schema types, rules, validation, workflow runtime and form session for form/workflow JSON. No DOM, no dependencies.",
6
9
  "license": "MIT",
7
10
  "author": "Nattapong Promthong",