@20baht/engine 0.0.0-stage → 0.1.0
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.
- package/LICENSE +21 -0
- package/README.md +52 -2
- package/dist/approval.d.ts +15 -0
- package/dist/approval.js +18 -0
- package/dist/dates.d.ts +34 -0
- package/dist/dates.js +91 -0
- package/dist/defaults.d.ts +6 -0
- package/dist/defaults.js +37 -0
- package/dist/display.d.ts +33 -0
- package/dist/display.js +110 -0
- package/dist/engine/conditions.d.ts +27 -0
- package/dist/engine/conditions.js +123 -0
- package/dist/engine/evaluate.d.ts +8 -0
- package/dist/engine/evaluate.js +368 -0
- package/dist/engine/expressions.d.ts +3 -0
- package/dist/engine/expressions.js +70 -0
- package/dist/engine/form-session.d.ts +129 -0
- package/dist/engine/form-session.js +310 -0
- package/dist/engine/graph.d.ts +40 -0
- package/dist/engine/graph.js +59 -0
- package/dist/engine/runtime.d.ts +173 -0
- package/dist/engine/runtime.js +237 -0
- package/dist/engine/scripts.d.ts +34 -0
- package/dist/engine/scripts.js +98 -0
- package/dist/flags.d.ts +19 -0
- package/dist/flags.js +49 -0
- package/dist/form-values.d.ts +78 -0
- package/dist/form-values.js +6 -0
- package/dist/i18n.d.ts +171 -0
- package/dist/i18n.js +298 -0
- package/dist/index.d.ts +25 -0
- package/dist/index.js +23 -0
- package/dist/keys.d.ts +14 -0
- package/dist/keys.js +4 -0
- package/dist/legacy.d.ts +14 -0
- package/dist/legacy.js +47 -0
- package/dist/pattern-safety.d.ts +34 -0
- package/dist/pattern-safety.js +267 -0
- package/dist/same-data.d.ts +5 -0
- package/dist/same-data.js +23 -0
- package/dist/shortcut.d.ts +44 -0
- package/dist/shortcut.js +176 -0
- package/dist/types.d.ts +541 -0
- package/dist/types.js +1 -0
- package/dist/urls.d.ts +8 -0
- package/dist/urls.js +30 -0
- package/dist/validators.d.ts +39 -0
- package/dist/validators.js +372 -0
- package/dist/views.d.ts +12 -0
- package/dist/views.js +11 -0
- package/package.json +49 -4
|
@@ -0,0 +1,310 @@
|
|
|
1
|
+
import { defaultValue } from '../defaults.js';
|
|
2
|
+
import { t } from '../i18n.js';
|
|
3
|
+
import { sameData } from '../same-data.js';
|
|
4
|
+
import { validateField } from '../validators.js';
|
|
5
|
+
import { resolveViewFields } from '../views.js';
|
|
6
|
+
import { createScriptContext, hasScripts, MAX_SCRIPT_DEPTH, runScripts, } from './scripts.js';
|
|
7
|
+
export const emptyFormState = Object.freeze({
|
|
8
|
+
edits: Object.freeze({}),
|
|
9
|
+
errors: Object.freeze([]),
|
|
10
|
+
scriptStates: Object.freeze({}),
|
|
11
|
+
fieldMessages: Object.freeze({}),
|
|
12
|
+
formMessages: Object.freeze([]),
|
|
13
|
+
});
|
|
14
|
+
const isStatic = (field) => field.type === 'label' || field.type === 'section';
|
|
15
|
+
function valueOf(input, state, field) {
|
|
16
|
+
if (Object.hasOwn(state.edits, field.key))
|
|
17
|
+
return state.edits[field.key];
|
|
18
|
+
if (input.value && Object.hasOwn(input.value, field.key))
|
|
19
|
+
return input.value[field.key];
|
|
20
|
+
return defaultValue(field);
|
|
21
|
+
}
|
|
22
|
+
export function formData(input, state) {
|
|
23
|
+
const data = {};
|
|
24
|
+
for (const field of input.form.fields) {
|
|
25
|
+
if (!isStatic(field))
|
|
26
|
+
data[field.key] = valueOf(input, state, field);
|
|
27
|
+
}
|
|
28
|
+
return data;
|
|
29
|
+
}
|
|
30
|
+
export function formFieldState(input, state, field) {
|
|
31
|
+
const base = input.fieldStates?.[field.key] ?? {
|
|
32
|
+
visible: true,
|
|
33
|
+
enabled: !field.disabled,
|
|
34
|
+
readonly: !!field.readonly,
|
|
35
|
+
required: !!field.required,
|
|
36
|
+
computed: false,
|
|
37
|
+
};
|
|
38
|
+
const override = state.scriptStates[field.key];
|
|
39
|
+
const merged = override ? { ...base, ...override } : base;
|
|
40
|
+
return field.hidden ? { ...merged, visible: false } : merged;
|
|
41
|
+
}
|
|
42
|
+
export function validateShownField(field, shown, value, registry, data, rowStates) {
|
|
43
|
+
if (shown && !shown.visible)
|
|
44
|
+
return [];
|
|
45
|
+
const required = shown ? shown.required : !!field.required;
|
|
46
|
+
const descriptor = required === !!field.required ? field : { ...field, required };
|
|
47
|
+
return validateField(descriptor, value, registry, data, rowStates);
|
|
48
|
+
}
|
|
49
|
+
function blocking(ok, messages) {
|
|
50
|
+
const errors = messages
|
|
51
|
+
.filter((m) => m.type === 'error')
|
|
52
|
+
.map((m) => ({ key: '$', message: m.message }));
|
|
53
|
+
if (!ok && errors.length === 0)
|
|
54
|
+
errors.push({ key: '$', message: t('scriptBlocked') });
|
|
55
|
+
return errors;
|
|
56
|
+
}
|
|
57
|
+
export function submitScriptErrors(form, registry, sink) {
|
|
58
|
+
if (!hasScripts(form, 'submit'))
|
|
59
|
+
return [];
|
|
60
|
+
let messages = [];
|
|
61
|
+
const g = createScriptContext(form, {
|
|
62
|
+
...sink,
|
|
63
|
+
addFormMessage: (message) => {
|
|
64
|
+
messages.push(message);
|
|
65
|
+
sink.addFormMessage(message);
|
|
66
|
+
},
|
|
67
|
+
clearFormMessages: () => {
|
|
68
|
+
messages = [];
|
|
69
|
+
sink.clearFormMessages();
|
|
70
|
+
},
|
|
71
|
+
});
|
|
72
|
+
const ok = runScripts({
|
|
73
|
+
form,
|
|
74
|
+
registry: registry ?? {},
|
|
75
|
+
g,
|
|
76
|
+
on: 'submit',
|
|
77
|
+
detail: { isLoading: false, data: { ...sink.getData() } },
|
|
78
|
+
});
|
|
79
|
+
return blocking(ok, messages);
|
|
80
|
+
}
|
|
81
|
+
class Step {
|
|
82
|
+
constructor(input, state, host) {
|
|
83
|
+
this.input = input;
|
|
84
|
+
this.state = state;
|
|
85
|
+
this.host = host;
|
|
86
|
+
this.events = [];
|
|
87
|
+
this.depth = 0;
|
|
88
|
+
this.context = null;
|
|
89
|
+
this.sink = {
|
|
90
|
+
getData: () => this.data(),
|
|
91
|
+
setValue: (key, value) => {
|
|
92
|
+
this.write(key, value);
|
|
93
|
+
},
|
|
94
|
+
setState: (key, patch) => {
|
|
95
|
+
const { scriptStates } = this.state;
|
|
96
|
+
this.patch({ scriptStates: { ...scriptStates, [key]: { ...scriptStates[key], ...patch } } });
|
|
97
|
+
},
|
|
98
|
+
resetState: (key) => {
|
|
99
|
+
if (key === undefined) {
|
|
100
|
+
this.patch({ scriptStates: {} });
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
const { [key]: _dropped, ...scriptStates } = this.state.scriptStates;
|
|
104
|
+
this.patch({ scriptStates });
|
|
105
|
+
},
|
|
106
|
+
setFieldMessage: (key, message) => {
|
|
107
|
+
const { [key]: _dropped, ...rest } = this.state.fieldMessages;
|
|
108
|
+
this.patch({ fieldMessages: message ? { ...rest, [key]: message } : rest });
|
|
109
|
+
},
|
|
110
|
+
addFormMessage: (message) => {
|
|
111
|
+
this.patch({ formMessages: [...this.state.formMessages, message] });
|
|
112
|
+
},
|
|
113
|
+
clearFormMessages: () => {
|
|
114
|
+
this.patch({ formMessages: [] });
|
|
115
|
+
},
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
get form() {
|
|
119
|
+
return this.input.form;
|
|
120
|
+
}
|
|
121
|
+
field(key) {
|
|
122
|
+
return this.form.fields.find((f) => f.key === key);
|
|
123
|
+
}
|
|
124
|
+
data() {
|
|
125
|
+
return formData(this.input, this.state);
|
|
126
|
+
}
|
|
127
|
+
patch(next) {
|
|
128
|
+
this.state = { ...this.state, ...next };
|
|
129
|
+
}
|
|
130
|
+
g() {
|
|
131
|
+
this.context ??= (this.host.context ?? createScriptContext)(this.form, this.sink);
|
|
132
|
+
return this.context;
|
|
133
|
+
}
|
|
134
|
+
clearDependents(changed) {
|
|
135
|
+
const queue = [changed];
|
|
136
|
+
const cleared = new Set();
|
|
137
|
+
for (let key = queue.shift(); key !== undefined; key = queue.shift()) {
|
|
138
|
+
for (const f of this.form.fields) {
|
|
139
|
+
if (!f.options_deps?.includes(key) || cleared.has(f.key))
|
|
140
|
+
continue;
|
|
141
|
+
cleared.add(f.key);
|
|
142
|
+
this.patch({ edits: { ...this.state.edits, [f.key]: defaultValue(f) } });
|
|
143
|
+
queue.push(f.key);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
write(key, value, revalidate = false) {
|
|
148
|
+
const before = this.data()[key];
|
|
149
|
+
this.patch({ edits: { ...this.state.edits, [key]: value } });
|
|
150
|
+
this.clearDependents(key);
|
|
151
|
+
if (revalidate && (this.input.validateOn ?? 'change') === 'change' && this.hasErrors()) {
|
|
152
|
+
this.patch({ errors: this.validators() });
|
|
153
|
+
}
|
|
154
|
+
this.events.push({
|
|
155
|
+
name: 'baht-change',
|
|
156
|
+
detail: { form_name: this.form.form_name, key, value, data: this.data() },
|
|
157
|
+
});
|
|
158
|
+
this.change(key, before, value, false);
|
|
159
|
+
}
|
|
160
|
+
hasErrors() {
|
|
161
|
+
return this.state.errors.length > 0;
|
|
162
|
+
}
|
|
163
|
+
input_(key, raw) {
|
|
164
|
+
const field = this.field(key);
|
|
165
|
+
if (!field || isStatic(field))
|
|
166
|
+
return;
|
|
167
|
+
const format = field.formatter ? this.input.registry?.formatters?.[field.formatter] : undefined;
|
|
168
|
+
if (field.formatter && !format) {
|
|
169
|
+
console.warn(`[bahtui] unknown formatter "${field.formatter}" — skipped`);
|
|
170
|
+
}
|
|
171
|
+
this.write(key, format ? format(raw) : raw, true);
|
|
172
|
+
}
|
|
173
|
+
set(patch) {
|
|
174
|
+
const before = this.data();
|
|
175
|
+
this.patch({ edits: { ...this.state.edits, ...patch } });
|
|
176
|
+
for (const key of Object.keys(patch))
|
|
177
|
+
this.change(key, before[key], patch[key], false);
|
|
178
|
+
}
|
|
179
|
+
revert(keys) {
|
|
180
|
+
if (!keys.some((key) => Object.hasOwn(this.state.edits, key)))
|
|
181
|
+
return;
|
|
182
|
+
this.patch({
|
|
183
|
+
edits: Object.fromEntries(Object.entries(this.state.edits).filter(([key]) => !keys.includes(key))),
|
|
184
|
+
});
|
|
185
|
+
}
|
|
186
|
+
valueReplaced(previous) {
|
|
187
|
+
const after = this.input.value ?? {};
|
|
188
|
+
const kept = Object.entries(this.state.edits).filter(([k]) => sameData(previous[k], after[k]));
|
|
189
|
+
if (kept.length !== Object.keys(this.state.edits).length) {
|
|
190
|
+
this.patch({ edits: Object.fromEntries(kept) });
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
formReplaced(previous) {
|
|
194
|
+
if (previous && previous.form_id !== this.form.form_id)
|
|
195
|
+
this.patch({ edits: {}, errors: [] });
|
|
196
|
+
this.patch({ scriptStates: {}, fieldMessages: {}, formMessages: [] });
|
|
197
|
+
}
|
|
198
|
+
change(key, oldValue, newValue, isLoading) {
|
|
199
|
+
if (!hasScripts(this.form, 'change', key))
|
|
200
|
+
return;
|
|
201
|
+
if (this.depth >= MAX_SCRIPT_DEPTH) {
|
|
202
|
+
console.warn(`[bahtui] script cascade on "${this.form.form_name}.${key}" exceeded ${String(MAX_SCRIPT_DEPTH)} levels — stopped (setValue ping-pong between change scripts?)`);
|
|
203
|
+
return;
|
|
204
|
+
}
|
|
205
|
+
this.depth++;
|
|
206
|
+
try {
|
|
207
|
+
runScripts({
|
|
208
|
+
form: this.form,
|
|
209
|
+
registry: this.input.registry ?? {},
|
|
210
|
+
g: this.g(),
|
|
211
|
+
on: 'change',
|
|
212
|
+
key,
|
|
213
|
+
detail: { oldValue, newValue, isLoading, data: this.data() },
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
finally {
|
|
217
|
+
this.depth--;
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
load() {
|
|
221
|
+
if (!this.form.scripts?.length)
|
|
222
|
+
return;
|
|
223
|
+
const data = this.data();
|
|
224
|
+
for (const f of this.form.fields) {
|
|
225
|
+
if (!isStatic(f))
|
|
226
|
+
this.change(f.key, undefined, data[f.key], true);
|
|
227
|
+
}
|
|
228
|
+
if (!hasScripts(this.form, 'load'))
|
|
229
|
+
return;
|
|
230
|
+
runScripts({
|
|
231
|
+
form: this.form,
|
|
232
|
+
registry: this.input.registry ?? {},
|
|
233
|
+
g: this.g(),
|
|
234
|
+
on: 'load',
|
|
235
|
+
detail: { isLoading: true, data: this.data() },
|
|
236
|
+
});
|
|
237
|
+
}
|
|
238
|
+
shown() {
|
|
239
|
+
const { form, view } = this.input;
|
|
240
|
+
return resolveViewFields(form, view) ?? resolveViewFields(form) ?? [];
|
|
241
|
+
}
|
|
242
|
+
validateOne(field, data) {
|
|
243
|
+
return validateShownField(field, formFieldState(this.input, this.state, field), valueOf(this.input, this.state, field), this.input.registry, data, this.input.fieldStates ?? {});
|
|
244
|
+
}
|
|
245
|
+
validators() {
|
|
246
|
+
const data = this.data();
|
|
247
|
+
return this.shown()
|
|
248
|
+
.filter((f) => !isStatic(f))
|
|
249
|
+
.flatMap((f) => this.validateOne(f, data));
|
|
250
|
+
}
|
|
251
|
+
validate() {
|
|
252
|
+
const errors = this.validators();
|
|
253
|
+
if (hasScripts(this.form, 'submit')) {
|
|
254
|
+
this.patch({ formMessages: [] });
|
|
255
|
+
const ok = runScripts({
|
|
256
|
+
form: this.form,
|
|
257
|
+
registry: this.input.registry ?? {},
|
|
258
|
+
g: this.g(),
|
|
259
|
+
on: 'submit',
|
|
260
|
+
detail: { isLoading: false, data: this.data() },
|
|
261
|
+
});
|
|
262
|
+
errors.push(...blocking(ok, this.state.formMessages));
|
|
263
|
+
}
|
|
264
|
+
this.patch({ errors });
|
|
265
|
+
this.events.push({ name: 'baht-validity', detail: { valid: errors.length === 0, errors } });
|
|
266
|
+
}
|
|
267
|
+
blur(key) {
|
|
268
|
+
const field = this.field(key);
|
|
269
|
+
if (!field || this.input.validateOn !== 'blur')
|
|
270
|
+
return;
|
|
271
|
+
const others = this.state.errors.filter((er) => er.key !== key);
|
|
272
|
+
this.patch({ errors: [...others, ...this.validateOne(field, this.data())] });
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
export function updateForm(input, state, msg, host = {}) {
|
|
276
|
+
const step = new Step(input, state, host);
|
|
277
|
+
switch (msg.type) {
|
|
278
|
+
case 'input':
|
|
279
|
+
step.input_(msg.key, msg.value);
|
|
280
|
+
break;
|
|
281
|
+
case 'set':
|
|
282
|
+
step.set(msg.patch);
|
|
283
|
+
break;
|
|
284
|
+
case 'revert':
|
|
285
|
+
step.revert(msg.keys);
|
|
286
|
+
break;
|
|
287
|
+
case 'value':
|
|
288
|
+
step.valueReplaced(msg.previous);
|
|
289
|
+
break;
|
|
290
|
+
case 'form':
|
|
291
|
+
step.formReplaced(msg.previous);
|
|
292
|
+
break;
|
|
293
|
+
case 'load':
|
|
294
|
+
step.load();
|
|
295
|
+
break;
|
|
296
|
+
case 'validate':
|
|
297
|
+
step.validate();
|
|
298
|
+
break;
|
|
299
|
+
case 'blur':
|
|
300
|
+
step.blur(msg.key);
|
|
301
|
+
break;
|
|
302
|
+
case 'script':
|
|
303
|
+
msg.write(step.sink);
|
|
304
|
+
break;
|
|
305
|
+
case 'reset':
|
|
306
|
+
step.state = emptyFormState;
|
|
307
|
+
break;
|
|
308
|
+
}
|
|
309
|
+
return { state: step.state, events: step.events };
|
|
310
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { Derived, DerivedFieldState, NestedData, WorkflowDefinition, WorkflowForm } from '../types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Graph routing (spec 03 §6). `transitions` turn the linear wizard into a
|
|
4
|
+
* graph: from a form, the first edge whose `when` matches wins; `to: 'end'`
|
|
5
|
+
* submits. Forms without outgoing edges — or whose edges all miss — fall
|
|
6
|
+
* back to the next visible form in `order`, so branches are added only where
|
|
7
|
+
* needed. Invisible targets (rule-hidden/skipped) are passed through to
|
|
8
|
+
* their own next hop.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* The forms a run can stand on, in `order`: every form the rules have not hidden or skipped.
|
|
12
|
+
* `derived` is what `evaluate()` returned for the data; without one, every form shows. The one
|
|
13
|
+
* definition for the element, the runtime and the server.
|
|
14
|
+
*/
|
|
15
|
+
export declare function visibleForms(workflow: WorkflowDefinition, derived?: Pick<Derived, 'forms'> | null): WorkflowForm[];
|
|
16
|
+
/**
|
|
17
|
+
* One step of a workflow rendered on its own: the rule-derived state of `formName`'s fields for
|
|
18
|
+
* this data, keyed as `<baht-form>.fieldStates` reads them (`key`, and `key[i].sub` for a
|
|
19
|
+
* repeater row's sub-field). The rules are the whole workflow's, so a condition may read another
|
|
20
|
+
* step's data (`Review.scanned`); pass what is known of it in `data`. For a run that lives on a
|
|
21
|
+
* server and is filled one step at a time, by different people: `@20baht/validator`'s
|
|
22
|
+
* `validateSubmission(workflow, body, …, { form, context })` checks the same step the same way.
|
|
23
|
+
*/
|
|
24
|
+
export declare function stepFieldStates(workflow: WorkflowDefinition, formName: string, data: NestedData): Record<string, DerivedFieldState>;
|
|
25
|
+
/**
|
|
26
|
+
* The step after `current` given the data: a form_name or 'end'. Rules run
|
|
27
|
+
* (via evaluate) to decide visibility; hidden targets pass through, cycles
|
|
28
|
+
* of invisible forms end the walk. `visibility` lets a caller that already
|
|
29
|
+
* ran the rules (walkPath — data never changes during a walk) skip the
|
|
30
|
+
* per-hop evaluate() fixpoint.
|
|
31
|
+
*/
|
|
32
|
+
export declare function resolveNext(workflow: WorkflowDefinition, current: string, data: NestedData, visibility?: ReadonlySet<string>): string;
|
|
33
|
+
/**
|
|
34
|
+
* The full path a submission takes from the start form to 'end' under this
|
|
35
|
+
* data — what the server validates against (off-path forms are as good as
|
|
36
|
+
* skipped). Back-edges that revisit a form stop the walk instead of looping.
|
|
37
|
+
* A caller that has already run `evaluate()` on this data passes the visible
|
|
38
|
+
* form names as `visibility` and saves the second fixpoint.
|
|
39
|
+
*/
|
|
40
|
+
export declare function walkPath(workflow: WorkflowDefinition, data: NestedData, visibility?: ReadonlySet<string>): string[];
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { evalCondition } from './conditions.js';
|
|
2
|
+
import { evaluate } from './evaluate.js';
|
|
3
|
+
export function visibleForms(workflow, derived) {
|
|
4
|
+
const forms = [...workflow.forms].sort((a, b) => a.order - b.order);
|
|
5
|
+
return derived ? forms.filter((f) => derived.forms[f.form_name]?.visible !== false) : forms;
|
|
6
|
+
}
|
|
7
|
+
export function stepFieldStates(workflow, formName, data) {
|
|
8
|
+
if (!workflow.forms.some((f) => f.form_name === formName))
|
|
9
|
+
return {};
|
|
10
|
+
const prefix = `${formName}.`;
|
|
11
|
+
const states = {};
|
|
12
|
+
for (const [ref, state] of Object.entries(evaluate(workflow, data).fields)) {
|
|
13
|
+
if (ref.startsWith(prefix))
|
|
14
|
+
states[ref.slice(prefix.length)] = state;
|
|
15
|
+
}
|
|
16
|
+
return states;
|
|
17
|
+
}
|
|
18
|
+
function visibleNames(workflow, data) {
|
|
19
|
+
return new Set(visibleForms(workflow, evaluate(workflow, data)).map((f) => f.form_name));
|
|
20
|
+
}
|
|
21
|
+
function hop(workflow, from, data) {
|
|
22
|
+
for (const t of workflow.transitions ?? []) {
|
|
23
|
+
if (t.from !== from)
|
|
24
|
+
continue;
|
|
25
|
+
if (evalCondition(t.when, data))
|
|
26
|
+
return t.to;
|
|
27
|
+
}
|
|
28
|
+
const sorted = [...workflow.forms].sort((a, b) => a.order - b.order);
|
|
29
|
+
const idx = sorted.findIndex((f) => f.form_name === from);
|
|
30
|
+
return idx >= 0 && idx + 1 < sorted.length ? sorted[idx + 1].form_name : 'end';
|
|
31
|
+
}
|
|
32
|
+
export function resolveNext(workflow, current, data, visibility) {
|
|
33
|
+
const visible = visibility ?? visibleNames(workflow, data);
|
|
34
|
+
const seen = new Set([current]);
|
|
35
|
+
let target = hop(workflow, current, data);
|
|
36
|
+
while (target !== 'end' && !visible.has(target)) {
|
|
37
|
+
if (seen.has(target))
|
|
38
|
+
return 'end';
|
|
39
|
+
seen.add(target);
|
|
40
|
+
target = hop(workflow, target, data);
|
|
41
|
+
}
|
|
42
|
+
return target;
|
|
43
|
+
}
|
|
44
|
+
export function walkPath(workflow, data, visibility) {
|
|
45
|
+
const visible = visibility ?? visibleNames(workflow, data);
|
|
46
|
+
const sorted = [...workflow.forms].sort((a, b) => a.order - b.order);
|
|
47
|
+
const start = sorted.find((f) => visible.has(f.form_name))?.form_name;
|
|
48
|
+
if (!start)
|
|
49
|
+
return [];
|
|
50
|
+
const path = [];
|
|
51
|
+
const seen = new Set();
|
|
52
|
+
let current = start;
|
|
53
|
+
while (current !== 'end' && !seen.has(current)) {
|
|
54
|
+
seen.add(current);
|
|
55
|
+
path.push(current);
|
|
56
|
+
current = resolveNext(workflow, current, data, visible);
|
|
57
|
+
}
|
|
58
|
+
return path;
|
|
59
|
+
}
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
import type { ApprovalDecision, Derived, NestedData, ValidationError, WorkflowDefinition, WorkflowForm } from '../types.js';
|
|
2
|
+
export type StepDirection = 'forward' | 'back';
|
|
3
|
+
/** A run: where it stands and what it holds. Plain data, safe to keep, compare and log. */
|
|
4
|
+
export interface WorkflowState {
|
|
5
|
+
/** `evaluate()` of the run's data. `derived.data` is the data: cleared and computed values included. */
|
|
6
|
+
derived: Derived;
|
|
7
|
+
/** `form_name` of the step showing, or `null` when no form is visible. */
|
|
8
|
+
current: string | null;
|
|
9
|
+
/** The steps walked to get here, oldest first: what `back` returns along. */
|
|
10
|
+
history: readonly string[];
|
|
11
|
+
/** The decision the user last tried needs a comment: a catalog key, `null` once it is given. */
|
|
12
|
+
approvalError: 'commentRequired' | null;
|
|
13
|
+
/** Which way the last navigation went; `null` before the first. */
|
|
14
|
+
direction: StepDirection | null;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* A run as JSON: what to keep to pick it up again later (another page load, another device)
|
|
18
|
+
* or to step back to (undo). The rules are not in it: `restore` runs them on `data` again.
|
|
19
|
+
*/
|
|
20
|
+
export interface WorkflowSnapshot {
|
|
21
|
+
data: NestedData;
|
|
22
|
+
current: string | null;
|
|
23
|
+
history: string[];
|
|
24
|
+
}
|
|
25
|
+
interface Validity {
|
|
26
|
+
valid: boolean;
|
|
27
|
+
errors: ValidationError[];
|
|
28
|
+
}
|
|
29
|
+
/** What can happen to a run. */
|
|
30
|
+
export type WorkflowMsg =
|
|
31
|
+
/** Begin (or begin again) from this data: first visible step, no history. */
|
|
32
|
+
{
|
|
33
|
+
type: 'start';
|
|
34
|
+
value: NestedData;
|
|
35
|
+
}
|
|
36
|
+
/** The workflow passed in was re-resolved against other flags: same data, other steps. */
|
|
37
|
+
| {
|
|
38
|
+
type: 'flags';
|
|
39
|
+
}
|
|
40
|
+
/** The user edited one field. */
|
|
41
|
+
| {
|
|
42
|
+
type: 'edit';
|
|
43
|
+
form_name: string;
|
|
44
|
+
key: string;
|
|
45
|
+
value: unknown;
|
|
46
|
+
}
|
|
47
|
+
/** The host wrote values into one form. */
|
|
48
|
+
| {
|
|
49
|
+
type: 'patch';
|
|
50
|
+
form_name: string;
|
|
51
|
+
patch: Record<string, unknown>;
|
|
52
|
+
}
|
|
53
|
+
/** The approval comment changed. */
|
|
54
|
+
| {
|
|
55
|
+
type: 'comment';
|
|
56
|
+
form_name: string;
|
|
57
|
+
value: string;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Next/Submit was pressed on a form the caller validated. With `gate`, an invalid form
|
|
61
|
+
* stays put and nothing is emitted. On an approval step this approves.
|
|
62
|
+
*/
|
|
63
|
+
| {
|
|
64
|
+
type: 'next';
|
|
65
|
+
validity: Validity;
|
|
66
|
+
gate: boolean;
|
|
67
|
+
}
|
|
68
|
+
/** Approve or reject the approval step showing. */
|
|
69
|
+
| {
|
|
70
|
+
type: 'decide';
|
|
71
|
+
decision: ApprovalDecision;
|
|
72
|
+
} | {
|
|
73
|
+
type: 'back';
|
|
74
|
+
} | {
|
|
75
|
+
type: 'gotoStart';
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Pick a kept run up again. The snapshot is untrusted (it was stored somewhere): the rules run
|
|
79
|
+
* 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.
|
|
81
|
+
*/
|
|
82
|
+
| {
|
|
83
|
+
type: 'restore';
|
|
84
|
+
snapshot: unknown;
|
|
85
|
+
};
|
|
86
|
+
/** The events a step can call for: the names and details `<baht-workflow>` dispatches. */
|
|
87
|
+
export interface WorkflowEventMap {
|
|
88
|
+
'baht-data-change': {
|
|
89
|
+
data: NestedData;
|
|
90
|
+
};
|
|
91
|
+
'baht-next': {
|
|
92
|
+
form_name: string;
|
|
93
|
+
order: number;
|
|
94
|
+
data: NestedData;
|
|
95
|
+
valid?: boolean;
|
|
96
|
+
errors?: ValidationError[];
|
|
97
|
+
decision?: ApprovalDecision;
|
|
98
|
+
comment?: string;
|
|
99
|
+
};
|
|
100
|
+
'baht-step-change': {
|
|
101
|
+
form_name: string;
|
|
102
|
+
order: number;
|
|
103
|
+
direction: StepDirection;
|
|
104
|
+
};
|
|
105
|
+
'baht-nav-blocked': {
|
|
106
|
+
form_name: string | null;
|
|
107
|
+
target: string;
|
|
108
|
+
reason: 'self-transition' | 'target-hidden';
|
|
109
|
+
data: NestedData;
|
|
110
|
+
};
|
|
111
|
+
'baht-submit': {
|
|
112
|
+
data: NestedData;
|
|
113
|
+
valid?: boolean;
|
|
114
|
+
errors?: ValidationError[];
|
|
115
|
+
decision?: ApprovalDecision;
|
|
116
|
+
comment?: string;
|
|
117
|
+
};
|
|
118
|
+
'baht-complete': {
|
|
119
|
+
data: NestedData;
|
|
120
|
+
status: 'completed' | 'rejected';
|
|
121
|
+
};
|
|
122
|
+
'baht-approve': ApprovalDetail;
|
|
123
|
+
'baht-reject': ApprovalDetail;
|
|
124
|
+
'baht-rule-error': {
|
|
125
|
+
errors: Derived['errors'];
|
|
126
|
+
};
|
|
127
|
+
}
|
|
128
|
+
interface ApprovalDetail {
|
|
129
|
+
form_name: string;
|
|
130
|
+
decision: ApprovalDecision;
|
|
131
|
+
comment: string;
|
|
132
|
+
data: NestedData;
|
|
133
|
+
}
|
|
134
|
+
export type WorkflowEvent = {
|
|
135
|
+
[K in keyof WorkflowEventMap]: {
|
|
136
|
+
name: K;
|
|
137
|
+
detail: WorkflowEventMap[K];
|
|
138
|
+
};
|
|
139
|
+
}[keyof WorkflowEventMap];
|
|
140
|
+
export interface WorkflowUpdate {
|
|
141
|
+
state: WorkflowState;
|
|
142
|
+
/** In the order to dispatch them. */
|
|
143
|
+
events: WorkflowEvent[];
|
|
144
|
+
}
|
|
145
|
+
/** One step of a run as it happened: what `<baht-workflow>` tells as `baht-transition`. */
|
|
146
|
+
export interface WorkflowTransition {
|
|
147
|
+
msg: WorkflowMsg;
|
|
148
|
+
/** `null` for the step that started the run. */
|
|
149
|
+
before: WorkflowState | null;
|
|
150
|
+
after: WorkflowState;
|
|
151
|
+
events: WorkflowEvent[];
|
|
152
|
+
}
|
|
153
|
+
/** The visible form the run stands on, or `null`. */
|
|
154
|
+
export declare function currentForm(workflow: WorkflowDefinition, state: Pick<WorkflowState, 'derived' | 'current'>): WorkflowForm | null;
|
|
155
|
+
/**
|
|
156
|
+
* Where Next would go from here: a `form_name`, or `'end'` (spec 03 §6). A caller that already
|
|
157
|
+
* holds `visibleForms(workflow, state.derived)` passes it as `visible` and saves the sort.
|
|
158
|
+
*/
|
|
159
|
+
export declare function nextTarget(workflow: WorkflowDefinition, state: Pick<WorkflowState, 'derived' | 'current'>, visible?: readonly WorkflowForm[]): string;
|
|
160
|
+
/**
|
|
161
|
+
* One step of a run. `workflow` is the definition as the run sees it (flags already applied);
|
|
162
|
+
* `state` is `null` before the first step. Pure: same arguments, same result.
|
|
163
|
+
*/
|
|
164
|
+
export declare function updateWorkflow(workflow: WorkflowDefinition, state: WorkflowState | null, msg: WorkflowMsg): WorkflowUpdate;
|
|
165
|
+
/**
|
|
166
|
+
* A log of messages, folded: the state the run reaches and every event on the way. From `from`,
|
|
167
|
+
* or from nothing. Exact for the rules and the navigation; what a host script wrote during the
|
|
168
|
+
* original run is in the log only as the edits it made.
|
|
169
|
+
*/
|
|
170
|
+
export declare function replayWorkflow(workflow: WorkflowDefinition, msgs: readonly WorkflowMsg[], from?: WorkflowState | null): WorkflowUpdate;
|
|
171
|
+
/** What to keep of a run to `restore` it later. */
|
|
172
|
+
export declare function snapshotOf(state: WorkflowState): WorkflowSnapshot;
|
|
173
|
+
export {};
|