@zeyos/zx 5.5.0 → 5.6.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.
Files changed (48) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
  3. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  4. package/dist/types/components/avatar/avatar.d.ts +91 -4
  5. package/dist/types/components/block-view/block-view.d.ts +205 -0
  6. package/dist/types/components/composer/composer.d.ts +736 -0
  7. package/dist/types/components/run-status/run-status.d.ts +393 -0
  8. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  9. package/dist/types/components/source-list/source-list.d.ts +177 -0
  10. package/dist/types/core/messages.d.ts +135 -0
  11. package/dist/types/index.d.ts +8 -0
  12. package/dist/types/internal/agent-model.d.ts +587 -0
  13. package/dist/types/internal/highlight.d.ts +24 -0
  14. package/dist/types/internal/presence-loop.d.ts +148 -0
  15. package/dist/zx-zeyos.esm.js +4648 -4513
  16. package/dist/zx-zeyos.esm.min.js +2 -2
  17. package/dist/zx.css +1927 -1
  18. package/dist/zx.esm.js +15769 -9194
  19. package/dist/zx.esm.min.js +27 -8
  20. package/dist/zx.global.js +15769 -9194
  21. package/dist/zx.global.min.js +27 -8
  22. package/dist/zx.min.css +1 -1
  23. package/docs/api.json +1166 -5
  24. package/docs/llms.md +455 -2
  25. package/docs/llms.txt +10 -1
  26. package/package.json +1 -1
  27. package/src/components/agent-thread/agent-thread.css +417 -0
  28. package/src/components/agent-thread/agent-thread.js +1365 -0
  29. package/src/components/approval-card/approval-card.css +289 -0
  30. package/src/components/approval-card/approval-card.js +1377 -0
  31. package/src/components/avatar/avatar.css +56 -1
  32. package/src/components/avatar/avatar.js +148 -26
  33. package/src/components/block-view/block-view.css +300 -0
  34. package/src/components/block-view/block-view.js +523 -0
  35. package/src/components/composer/composer.css +403 -0
  36. package/src/components/composer/composer.js +1441 -0
  37. package/src/components/run-status/run-status.css +208 -0
  38. package/src/components/run-status/run-status.js +782 -0
  39. package/src/components/run-trace/run-trace.css +443 -0
  40. package/src/components/run-trace/run-trace.js +1209 -0
  41. package/src/components/source-list/source-list.css +208 -0
  42. package/src/components/source-list/source-list.js +355 -0
  43. package/src/core/messages.js +143 -0
  44. package/src/index.js +8 -0
  45. package/src/internal/agent-model.js +488 -0
  46. package/src/internal/highlight.js +104 -0
  47. package/src/internal/presence-loop.js +343 -0
  48. package/styles/zx.css +7 -0
@@ -0,0 +1,596 @@
1
+ import { Component } from '../../core/component.js';
2
+ import { Dialog } from '../dialog/dialog.js';
3
+ import { Field } from '../field/field.js';
4
+ import { Fieldset } from '../fieldset/fieldset.js';
5
+ export type Block = import('../../internal/agent-model.js').Block;
6
+ export type FieldOptions = import('../field/field.js').FieldOptions;
7
+ export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
8
+ export type ApprovalReasonMode = 'optional' | 'required' | 'none';
9
+ export type ApprovalAction = 'approve' | 'edit' | 'reject';
10
+ export type ApprovalTone = 'slate' | 'blue' | 'teal' | 'green' | 'amber' | 'orange' | 'red' | 'pink' | 'violet';
11
+ export type ApprovalPreview = {
12
+ /**
13
+ * Text of the disclosure button; "Preview" when absent.
14
+ */
15
+ label?: string;
16
+ /**
17
+ * What the disclosure shows: a node, or blocks.
18
+ */
19
+ content?: Node | Block[];
20
+ /**
21
+ * The same as `content` given as blocks, as the thread model spells it.
22
+ */
23
+ blocks?: Block[];
24
+ };
25
+ export type ApprovalCardOptions = {
26
+ /**
27
+ * What the agent wants to do, as a question: "Send 3 payment reminders?".
28
+ */
29
+ title?: string;
30
+ /**
31
+ * One line under the title: what follows from approving.
32
+ */
33
+ description?: string;
34
+ /**
35
+ * Icon name for the tile beside the title; none when null.
36
+ */
37
+ icon?: string | null;
38
+ /**
39
+ * Categorical tone of the icon tile.
40
+ */
41
+ tone?: ApprovalTone;
42
+ /**
43
+ * Element level of the title heading.
44
+ */
45
+ headingLevel?: 2 | 3 | 4 | 5 | 6;
46
+ /**
47
+ * Where the request stands.
48
+ */
49
+ status?: ApprovalStatus;
50
+ /**
51
+ * What will happen — recipients, amounts, records —
52
+ * as a node the application built, or as blocks. Model text in blocks is drawn as text only.
53
+ */
54
+ details?: Node | Block[] | null;
55
+ /**
56
+ * What the request produces, behind a disclosure.
57
+ */
58
+ preview?: ApprovalPreview | null;
59
+ /**
60
+ * The Edit form, keyed by value name.
61
+ * No fields, no Edit.
62
+ */
63
+ fields?: Record<string, FieldOptions> | null;
64
+ /**
65
+ * The values the request carries; the Edit form
66
+ * starts from them and `approve` reports them.
67
+ */
68
+ values?: Record<string, unknown>;
69
+ /**
70
+ * Text the person must type before Approve goes
71
+ * through, for an action that cannot be undone. Decided by the application from the tool the
72
+ * action triggers, never taken from model output.
73
+ */
74
+ confirmText?: string | null;
75
+ /**
76
+ * Whether Reject asks why.
77
+ */
78
+ reason?: ApprovalReasonMode;
79
+ /**
80
+ * Whether the values were already edited, for a request
81
+ * restored from a record. Without `editedKeys` every field is listed under "Edited by you".
82
+ */
83
+ edited?: boolean;
84
+ /**
85
+ * Which values were edited: only these fields are
86
+ * listed under "Edited by you", in field order. A non-empty list implies `edited`; null lists
87
+ * every field of an edited request.
88
+ */
89
+ editedKeys?: string[] | null;
90
+ /**
91
+ * The reason a rejected request was given, for a
92
+ * request restored from a record.
93
+ */
94
+ rejectReason?: string | null;
95
+ /**
96
+ * Who answers, as the verdict names them; the message
97
+ * `approvalCard.you` ("you") when null.
98
+ */
99
+ answeredBy?: string | null;
100
+ /**
101
+ * When an answered request was answered: a local
102
+ * ISO date-time or a Date. An answer given on the card takes the time it was given.
103
+ */
104
+ answeredAt?: string | Date | null;
105
+ /**
106
+ * The clock: decides whether `answeredAt` is today (the
107
+ * time alone) or another day (date and time), and gives the time of an answer recorded without
108
+ * an explicit `at`. Real time when null.
109
+ */
110
+ now?: (() => Date) | null;
111
+ /**
112
+ * Whether A, E, and R act while focus is inside the pending card.
113
+ * `handleKey()` works either way.
114
+ */
115
+ keys?: boolean;
116
+ /**
117
+ * Localized messages.
118
+ */
119
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
120
+ /**
121
+ * Approve listener.
122
+ */
123
+ onapprove?: (event: CustomEvent<{
124
+ values: Record<string, unknown>;
125
+ }>) => void;
126
+ /**
127
+ * Edit listener.
128
+ */
129
+ onedit?: (event: CustomEvent<ApprovalEditDetail>) => void;
130
+ /**
131
+ * Reject listener.
132
+ */
133
+ onreject?: (event: CustomEvent<{
134
+ reason: string;
135
+ }>) => void;
136
+ };
137
+ export type ApprovalCardUpdate = Pick<ApprovalCardOptions, 'title' | 'description' | 'icon' | 'tone' | 'details' | 'preview' | 'fields' | 'values' | 'confirmText' | 'reason' | 'edited' | 'editedKeys'>;
138
+ export type ApprovalEditDetail = {
139
+ /**
140
+ * The values as saved, edits included.
141
+ */
142
+ values: Record<string, unknown>;
143
+ /**
144
+ * The fields this save changed against the values before it, in
145
+ * field order; empty when the form was saved unchanged.
146
+ */
147
+ changed: string[];
148
+ /**
149
+ * Every field edited so far, this save included: what the
150
+ * card lists under "Edited by you" unless the edit is prevented. Null when the card lists every
151
+ * field (`edited: true` with no `editedKeys`).
152
+ */
153
+ editedKeys: string[] | null;
154
+ };
155
+ /**
156
+ * Which run state draws each request status: its glyph and tone come from `STATUS`, so a waiting
157
+ * request looks like a waiting step.
158
+ * @type {Readonly<Record<ApprovalStatus, import('../../internal/agent-model.js').RunState>>}
159
+ */
160
+ export declare const APPROVAL_STATES: Readonly<Record<ApprovalStatus, import('../../internal/agent-model.js').RunState>>;
161
+ /**
162
+ * A request that holds an agent's run until a person answers it: what the agent wants to do, what
163
+ * will happen, what it will produce, and Approve, Edit, and Reject. Answered, it freezes into the
164
+ * record of what was decided, by whom, and when.
165
+ *
166
+ * The card never acts on its own: it emits the answer, and the application carries it out. Every
167
+ * answer is preventable, so the application can refuse or defer one and settle the card later
168
+ * through `setStatus()`. A request the agent revises while it waits changes in place through
169
+ * `update()`, which keeps focus where it was.
170
+ *
171
+ * A, E, and R act while focus is inside a pending card and not in a text control; the card never
172
+ * listens to the document. An application that wants the keys from elsewhere forwards them to
173
+ * `handleKey()`.
174
+ *
175
+ * @fires ApprovalCard#approve
176
+ * @fires ApprovalCard#edit
177
+ * @fires ApprovalCard#reject
178
+ * @extends {Component<ApprovalCardOptions>}
179
+ */
180
+ export declare class ApprovalCard extends Component<ApprovalCardOptions> {
181
+ /** @type {import('../../core/dom.js').TargetSnapshot|null} */
182
+ _original: import('../../core/dom.js').TargetSnapshot | null;
183
+ _destroyed: boolean;
184
+ /** @type {ApprovalStatus} */
185
+ _status: ApprovalStatus;
186
+ /** @type {Record<string, unknown>} */
187
+ _values: Record<string, unknown>;
188
+ /** @type {Record<string, FieldOptions>|null} */
189
+ _fields: Record<string, FieldOptions> | null;
190
+ _edited: any;
191
+ /** @type {string[]|null} The values listed as edited; null lists every field. */
192
+ _editedKeys: string[] | null;
193
+ /** @type {(() => Date)|null} */
194
+ _clock: (() => Date) | null;
195
+ /** @type {string|null} */
196
+ _by: string | null;
197
+ /** @type {Date|null} */
198
+ _at: Date | null;
199
+ /** @type {string|null} */
200
+ _reason: string | null;
201
+ /** @type {ApprovalReasonMode} */
202
+ _reasonMode: ApprovalReasonMode;
203
+ _title: any;
204
+ _description: any;
205
+ /** @type {string|null} */
206
+ _icon: string | null;
207
+ _tone: any;
208
+ _confirmText: any;
209
+ /** @type {unknown} What `details` was drawn from, to compare an update against. */
210
+ _details: unknown;
211
+ /** @type {{label: string, content: unknown}|null} What the preview was drawn from. */
212
+ _preview: {
213
+ label: string;
214
+ content: unknown;
215
+ } | null;
216
+ /** @type {{dialog: Dialog, fieldset: Fieldset, fields: Record<string, FieldOptions>}|null} */
217
+ _editor: {
218
+ dialog: Dialog;
219
+ fieldset: Fieldset;
220
+ fields: Record<string, FieldOptions>;
221
+ } | null;
222
+ /** @type {{dialog: Dialog, field: Field, blocked: boolean, mode: ApprovalReasonMode}|null} */
223
+ _rejecter: {
224
+ dialog: Dialog;
225
+ field: Field;
226
+ blocked: boolean;
227
+ mode: ApprovalReasonMode;
228
+ } | null;
229
+ /** @type {Dialog|null} The type-to-confirm dialog while it is open. */
230
+ _confirm: Dialog | null;
231
+ _confirming: boolean;
232
+ _keys: boolean;
233
+ _descriptionId: string;
234
+ _blockLevel: 2 | 3 | 4 | 5;
235
+ _titleEl: HTMLElement;
236
+ _noteEl: HTMLElement;
237
+ _statusEl: HTMLElement;
238
+ /** @type {HTMLElement|null} */
239
+ _tileEl: HTMLElement | null;
240
+ /** @type {HTMLElement|null} */
241
+ _descriptionEl: HTMLElement | null;
242
+ _headEl: HTMLElement;
243
+ _changesEl: HTMLElement;
244
+ _reasonEl: HTMLElement;
245
+ /** @type {HTMLElement|null} */
246
+ _detailsEl: HTMLElement | null;
247
+ /** @type {HTMLElement|null} */
248
+ _previewEl: HTMLElement | null;
249
+ /** @type {HTMLElement|null} */
250
+ _previewToggle: HTMLElement | null;
251
+ /** @type {HTMLElement|null} */
252
+ _previewLabel: HTMLElement | null;
253
+ /** @type {HTMLElement|null} */
254
+ _previewBody: HTMLElement | null;
255
+ _approveEl: HTMLButtonElement;
256
+ /** @type {HTMLButtonElement|null} */
257
+ _editEl: HTMLButtonElement | null;
258
+ _rejectEl: HTMLButtonElement;
259
+ _actionsEl: HTMLElement;
260
+ static cssName: string;
261
+ /** @type {Readonly<ApprovalCardOptions>} */
262
+ static defaults: Readonly<ApprovalCardOptions>;
263
+ /** @returns {HTMLElement} */
264
+ render(): HTMLElement;
265
+ /**
266
+ * Changes the request in place — the agent revised it, or the record it is drawn from changed —
267
+ * and redraws only what changed. Focus stays where it was; when the element that held it is
268
+ * gone (the Edit button, the preview toggle), the card takes it. Of the card's dialogs only one
269
+ * the change makes meaningless closes: the Edit form when `fields` change, the Reject dialog
270
+ * when `reason` changes, the typed confirmation when `confirmText` changes. An open Edit form
271
+ * stays open over new `values` and saves what the person typed. Emits nothing.
272
+ *
273
+ * `edited` and `editedKeys` follow the options' rules: `edited: true` alone keeps the fields
274
+ * already listed (every field, on a card that was not edited); `edited: false` alone clears the
275
+ * list; a non-empty `editedKeys` marks the card edited.
276
+ * @param {ApprovalCardUpdate} [partial={}] The options to change; the rest stay as they are.
277
+ * @returns {this}
278
+ */
279
+ update(partial?: ApprovalCardUpdate): this;
280
+ /**
281
+ * Settles the request from outside: an answer the application received elsewhere, a request
282
+ * that timed out, or a prevented answer the application has now carried out. Emits nothing.
283
+ * @param {ApprovalStatus} status New status.
284
+ * @param {{by?: string|null, at?: string|Date|null, reason?: string|null}} [answer={}] Who answered,
285
+ * when (now, by the `now` clock, when left out), and the reason a rejection was given.
286
+ * @returns {this}
287
+ */
288
+ setStatus(status: ApprovalStatus, answer?: {
289
+ by?: string | null;
290
+ at?: string | Date | null;
291
+ reason?: string | null;
292
+ }): this;
293
+ /** @returns {ApprovalStatus} Where the request stands. */
294
+ getStatus(): ApprovalStatus;
295
+ /** @returns {Record<string, unknown>} A copy of the values, edits included. */
296
+ getValues(): Record<string, unknown>;
297
+ /**
298
+ * @returns {string[]|null} The fields listed under "Edited by you", in field order: empty when
299
+ * the request was not edited, null when every field is listed.
300
+ */
301
+ getEditedKeys(): string[] | null;
302
+ /**
303
+ * Moves focus to the card, so a thread can bring the reader to a request when a run starts
304
+ * waiting on it.
305
+ * @param {FocusOptions} [options] Native focus options.
306
+ * @returns {this}
307
+ */
308
+ focus(options?: FocusOptions): this;
309
+ /**
310
+ * Answers a key: A approves, E edits, R rejects. Acts only while the request is pending, never
311
+ * from a text control or with a modifier held, and never while one of the card's dialogs is
312
+ * open. The card calls it for keys inside itself; an application may forward keys from
313
+ * elsewhere.
314
+ * @param {KeyboardEvent} event Key event.
315
+ * @returns {boolean} Whether the key was used; a used key has its default prevented.
316
+ */
317
+ handleKey(event: KeyboardEvent): boolean;
318
+ /** @returns {void} */
319
+ destroy(): void;
320
+ /** @private @returns {boolean} Whether one of the card's dialogs is open or opening. */
321
+ private _busy;
322
+ /** @private @returns {boolean} Whether one of the card's dialogs is open. */
323
+ private _dialogOpen;
324
+ /** @private @returns {Date} Now, by the `now` clock when there is one. */
325
+ private _now;
326
+ /** @private @param {MouseEvent} event @returns {void} */
327
+ private _onClick;
328
+ /** @private @param {ApprovalAction} action @returns {void} */
329
+ private _run;
330
+ /** @private @returns {void} */
331
+ private _togglePreview;
332
+ /**
333
+ * Approves, after the typed confirmation when the request asks for one.
334
+ * @private
335
+ * @returns {Promise<void>}
336
+ */
337
+ private _requestApprove;
338
+ /** @private @returns {void} */
339
+ private _openEdit;
340
+ /**
341
+ * The Edit dialog, built the first time it is needed.
342
+ * @private
343
+ * @param {Record<string, FieldOptions>} fields
344
+ * @returns {{dialog: Dialog, fieldset: Fieldset, fields: Record<string, FieldOptions>}}
345
+ */
346
+ private _buildEditor;
347
+ /** @private @returns {void} */
348
+ private _saveEdit;
349
+ /** @private @returns {void} */
350
+ private _requestReject;
351
+ /**
352
+ * The Reject dialog, built the first time it is needed.
353
+ * @private
354
+ * @returns {{dialog: Dialog, field: Field, blocked: boolean, mode: ApprovalReasonMode}}
355
+ */
356
+ private _buildRejecter;
357
+ /** @private @returns {Field} The reason textarea, required or optional as the request asks. */
358
+ private _reasonField;
359
+ /**
360
+ * @private
361
+ * @param {boolean} blocked Whether Reject is held until a reason is given.
362
+ * @returns {import('../dialog/dialog.js').DialogButton[]}
363
+ */
364
+ private _rejectButtons;
365
+ /** @private @returns {void} */
366
+ private _syncRejectButton;
367
+ /** @private @returns {void} */
368
+ private _confirmReject;
369
+ /** @private @param {string} reason @returns {void} */
370
+ private _commitReject;
371
+ /**
372
+ * Freezes the card into its record, answered now by whoever `answeredBy` names.
373
+ * @private
374
+ * @param {'approved'|'rejected'} status
375
+ * @param {string|null} reason
376
+ * @returns {void}
377
+ */
378
+ private _answer;
379
+ /** @private @returns {void} */
380
+ private _closeDialogs;
381
+ /** @private @returns {string} Who answers, as the verdict names them. */
382
+ private _byText;
383
+ /** @private @returns {void} Draws the icon tile, or takes it away when there is no icon. */
384
+ private _drawTile;
385
+ /** @private @returns {void} Draws the line under the title, and what describes the card. */
386
+ private _drawDescription;
387
+ /** @private @param {unknown} details @returns {void} */
388
+ private _drawDetails;
389
+ /**
390
+ * Draws the preview disclosure, keeping its toggle — and whether it is open — across a change.
391
+ * @private
392
+ * @param {{label: string, content: unknown}|null} preview
393
+ * @returns {void}
394
+ */
395
+ private _drawPreview;
396
+ /** @private @returns {void} Adds the Edit button when there are fields, and takes it away when not. */
397
+ private _drawEditButton;
398
+ /**
399
+ * Draws everything that follows the status and the edits.
400
+ * @private
401
+ * @returns {void}
402
+ */
403
+ private _sync;
404
+ /**
405
+ * Draws what follows the status: the state glyph and word, the line under the title, the
406
+ * reason, and whether the actions show.
407
+ * @private
408
+ * @returns {void}
409
+ */
410
+ private _drawState;
411
+ /** @private @returns {void} Draws "Edited by you" over the edited values, or nothing. */
412
+ private _drawChanges;
413
+ }
414
+ /**
415
+ * Fired when Approve goes through: after the typed confirmation when one is asked for.
416
+ * Preventable: a prevented approval leaves the card pending.
417
+ * @event ApprovalCard#approve
418
+ * @type {CustomEvent<{values: Record<string, unknown>}>}
419
+ */
420
+ /**
421
+ * Fired when the Edit form is saved, with the values as saved, the fields this save changed, and
422
+ * every field edited so far. Preventable: a prevented edit keeps the earlier values and the
423
+ * earlier list of edited fields.
424
+ * @event ApprovalCard#edit
425
+ * @type {CustomEvent<ApprovalEditDetail>}
426
+ */
427
+ /**
428
+ * Fired when Reject goes through, with the reason given (empty when none was).
429
+ * Preventable: a prevented rejection leaves the card pending.
430
+ * @event ApprovalCard#reject
431
+ * @type {CustomEvent<{reason: string}>}
432
+ */
433
+ /**
434
+ * Reads a request status, falling back to `pending` for anything unknown.
435
+ * @param {unknown} status
436
+ * @returns {ApprovalStatus}
437
+ */
438
+ export declare function normalizeApprovalStatus(status: unknown): ApprovalStatus;
439
+ /**
440
+ * Reads a reason mode, falling back to `optional`.
441
+ * @param {unknown} reason
442
+ * @returns {ApprovalReasonMode}
443
+ */
444
+ export declare function normalizeReasonMode(reason: unknown): ApprovalReasonMode;
445
+ /**
446
+ * The action a key asks for, or null: A approves, E edits (only with an Edit form), R rejects —
447
+ * on a pending request, outside text controls, with no modifier held, and not while an input
448
+ * method is composing or the key repeats.
449
+ * @param {{key?: string, altKey?: boolean, ctrlKey?: boolean, metaKey?: boolean, shiftKey?: boolean,
450
+ * isComposing?: boolean, repeat?: boolean, defaultPrevented?: boolean}|null|undefined} event Key event.
451
+ * @param {{status: ApprovalStatus, canEdit?: boolean, editable?: boolean}} state The card's state,
452
+ * and whether the key came from a text control.
453
+ * @returns {ApprovalAction|null}
454
+ */
455
+ export declare function approvalKeyAction(event: {
456
+ key?: string;
457
+ altKey?: boolean;
458
+ ctrlKey?: boolean;
459
+ metaKey?: boolean;
460
+ shiftKey?: boolean;
461
+ isComposing?: boolean;
462
+ repeat?: boolean;
463
+ defaultPrevented?: boolean;
464
+ } | null | undefined, state: {
465
+ status: ApprovalStatus;
466
+ canEdit?: boolean;
467
+ editable?: boolean;
468
+ }): ApprovalAction | null;
469
+ /**
470
+ * The line under the title: the pause note while pending, otherwise who answered and when.
471
+ * @param {ApprovalStatus} status
472
+ * @param {{by?: string, time?: string}} [answer={}] Who answered, and the formatted time.
473
+ * @returns {{key: string, args: string[]}} Message key and its arguments.
474
+ */
475
+ export declare function approvalVerdict(status: ApprovalStatus, { by, time }?: {
476
+ by?: string;
477
+ time?: string;
478
+ }): {
479
+ key: string;
480
+ args: string[];
481
+ };
482
+ /**
483
+ * The line under the title for a request as it stands, the answer time written against `now`:
484
+ * the clock alone on the same day, the date as well on another.
485
+ * @param {ApprovalStatus} status
486
+ * @param {{by?: string, at?: string|Date|null, now?: Date|null}} [answer={}] Who answered, when,
487
+ * and the time it is now (real time when null).
488
+ * @returns {{key: string, args: string[]}} Message key and its arguments.
489
+ */
490
+ export declare function answerVerdict(status: ApprovalStatus, { by, at, now }?: {
491
+ by?: string;
492
+ at?: string | Date | null;
493
+ now?: Date | null;
494
+ }): {
495
+ key: string;
496
+ args: string[];
497
+ };
498
+ /**
499
+ * Reads a list of edited value names: the distinct non-empty strings, in the order given, or
500
+ * null when it is not a list.
501
+ * @param {unknown} keys
502
+ * @returns {string[]|null}
503
+ */
504
+ export declare function normalizeEditedKeys(keys: unknown): string[] | null;
505
+ /**
506
+ * Whether a request reads as edited, and which values it lists as edited. A non-empty
507
+ * `editedKeys` marks it edited; `edited` without a list lists every field.
508
+ * @param {unknown} edited The `edited` option.
509
+ * @param {unknown} editedKeys The `editedKeys` option.
510
+ * @returns {{edited: boolean, keys: string[]|null}} The values to list: null for every field,
511
+ * empty when the request was not edited.
512
+ */
513
+ export declare function editedState(edited: unknown, editedKeys: unknown): {
514
+ edited: boolean;
515
+ keys: string[] | null;
516
+ };
517
+ /**
518
+ * The fields edited so far once another save is added: the union, in field order, with names
519
+ * no field has kept at the end. Null — every field — stays null.
520
+ * @param {string[]|null|undefined} current The fields edited before.
521
+ * @param {string[]|null|undefined} added The fields the save changed.
522
+ * @param {Record<string, unknown>|null} [fields=null] The Edit form, for the order.
523
+ * @returns {string[]|null}
524
+ */
525
+ export declare function mergeEditedKeys(current: string[] | null | undefined, added: string[] | null | undefined, fields?: Record<string, unknown> | null): string[] | null;
526
+ /**
527
+ * Whether two option values are the same: equal primitives, dates at the same time, and arrays
528
+ * and plain objects with the same contents. Anything else — a node, a function — only when it is
529
+ * the very same object.
530
+ * @param {unknown} a
531
+ * @param {unknown} b
532
+ * @returns {boolean}
533
+ */
534
+ export declare function sameValue(a: unknown, b: unknown): boolean;
535
+ /**
536
+ * Reads a time: a Date, a local ISO date-time ("2026-11-03T10:31"), or epoch milliseconds.
537
+ * @param {unknown} value
538
+ * @returns {Date|null}
539
+ */
540
+ export declare function toDate(value: unknown): Date | null;
541
+ /**
542
+ * How an answer time is written: the clock alone on the day it is read, the day and month within
543
+ * the year, and the full date before that.
544
+ * @param {Date} date
545
+ * @param {Date} [now=new Date()]
546
+ * @returns {string} A `formatDate()` pattern.
547
+ */
548
+ export declare function answeredTimeFormat(date: Date, now?: Date): string;
549
+ /**
550
+ * An answer time as the verdict writes it: "10:31", "2 Nov, 10:31", "2 Nov 2025, 10:31".
551
+ * @param {Date} date
552
+ * @param {Date} [now=new Date()]
553
+ * @returns {string}
554
+ */
555
+ export declare function formatAnsweredAt(date: Date, now?: Date): string;
556
+ /**
557
+ * Whether a value counts as not given: nothing, blank text, or an empty list.
558
+ * @param {unknown} value
559
+ * @returns {boolean}
560
+ */
561
+ export declare function isEmptyValue(value: unknown): boolean;
562
+ /**
563
+ * The fields whose value differs between two sets of values. Nothing, `undefined`, and empty text
564
+ * count as the same.
565
+ * @param {Record<string, unknown>|null} fields
566
+ * @param {Record<string, unknown>} before
567
+ * @param {Record<string, unknown>} after
568
+ * @returns {string[]} Field keys, in field order.
569
+ */
570
+ export declare function changedKeys(fields: Record<string, unknown> | null, before: Record<string, unknown>, after: Record<string, unknown>): string[];
571
+ /**
572
+ * A value as the list of edited values shows it. A choice field's option label stands for its
573
+ * value; a list joins with commas.
574
+ * @param {unknown} value
575
+ * @param {{options?: unknown}|null} [field]
576
+ * @returns {string} The text, or '' for no value.
577
+ */
578
+ export declare function displayValue(value: unknown, field?: {
579
+ options?: unknown;
580
+ } | null): string;
581
+ /**
582
+ * The edited values to list: the changed fields when they are known, otherwise every field.
583
+ * A request restored from a record with no fields lists every value it carries.
584
+ * @param {Record<string, {label?: string, options?: unknown}>|null} fields
585
+ * @param {Record<string, unknown>} values
586
+ * @param {Set<string>|string[]|null} changed The edited values to list; null for every field.
587
+ * @returns {Array<{key: string, label: string, text: string}>} In field order.
588
+ */
589
+ export declare function editedEntries(fields: Record<string, {
590
+ label?: string;
591
+ options?: unknown;
592
+ }> | null, values: Record<string, unknown>, changed: Set<string> | string[] | null): Array<{
593
+ key: string;
594
+ label: string;
595
+ text: string;
596
+ }>;