@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.
- package/CHANGELOG.md +56 -0
- package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
- package/dist/types/components/approval-card/approval-card.d.ts +596 -0
- package/dist/types/components/avatar/avatar.d.ts +91 -4
- package/dist/types/components/block-view/block-view.d.ts +205 -0
- package/dist/types/components/composer/composer.d.ts +736 -0
- package/dist/types/components/run-status/run-status.d.ts +393 -0
- package/dist/types/components/run-trace/run-trace.d.ts +624 -0
- package/dist/types/components/source-list/source-list.d.ts +177 -0
- package/dist/types/core/messages.d.ts +135 -0
- package/dist/types/index.d.ts +8 -0
- package/dist/types/internal/agent-model.d.ts +587 -0
- package/dist/types/internal/highlight.d.ts +24 -0
- package/dist/types/internal/presence-loop.d.ts +148 -0
- package/dist/zx-zeyos.esm.js +4648 -4513
- package/dist/zx-zeyos.esm.min.js +2 -2
- package/dist/zx.css +1927 -1
- package/dist/zx.esm.js +15769 -9194
- package/dist/zx.esm.min.js +27 -8
- package/dist/zx.global.js +15769 -9194
- package/dist/zx.global.min.js +27 -8
- package/dist/zx.min.css +1 -1
- package/docs/api.json +1166 -5
- package/docs/llms.md +455 -2
- package/docs/llms.txt +10 -1
- package/package.json +1 -1
- package/src/components/agent-thread/agent-thread.css +417 -0
- package/src/components/agent-thread/agent-thread.js +1365 -0
- package/src/components/approval-card/approval-card.css +289 -0
- package/src/components/approval-card/approval-card.js +1377 -0
- package/src/components/avatar/avatar.css +56 -1
- package/src/components/avatar/avatar.js +148 -26
- package/src/components/block-view/block-view.css +300 -0
- package/src/components/block-view/block-view.js +523 -0
- package/src/components/composer/composer.css +403 -0
- package/src/components/composer/composer.js +1441 -0
- package/src/components/run-status/run-status.css +208 -0
- package/src/components/run-status/run-status.js +782 -0
- package/src/components/run-trace/run-trace.css +443 -0
- package/src/components/run-trace/run-trace.js +1209 -0
- package/src/components/source-list/source-list.css +208 -0
- package/src/components/source-list/source-list.js +355 -0
- package/src/core/messages.js +143 -0
- package/src/index.js +8 -0
- package/src/internal/agent-model.js +488 -0
- package/src/internal/highlight.js +104 -0
- package/src/internal/presence-loop.js +343 -0
- package/styles/zx.css +7 -0
|
@@ -0,0 +1,1377 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
import { Component } from '../../core/component.js';
|
|
3
|
+
import { formatDate } from '../../core/date.js';
|
|
4
|
+
import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
|
|
5
|
+
import { icon } from '../../core/icons.js';
|
|
6
|
+
import { isEditableTarget } from '../../core/keyboard.js';
|
|
7
|
+
import { uid } from '../../core/util.js';
|
|
8
|
+
import { STATUS } from '../../internal/agent-model.js';
|
|
9
|
+
import { renderBlocks } from '../block-view/block-view.js';
|
|
10
|
+
import { button } from '../button/button.js';
|
|
11
|
+
import { Dialog } from '../dialog/dialog.js';
|
|
12
|
+
import { Field } from '../field/field.js';
|
|
13
|
+
import { Fieldset } from '../fieldset/fieldset.js';
|
|
14
|
+
import { statusIcon } from '../select/glyphs.js';
|
|
15
|
+
|
|
16
|
+
/** @typedef {import('../../internal/agent-model.js').Block} Block */
|
|
17
|
+
/** @typedef {import('../field/field.js').FieldOptions} FieldOptions */
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Where a request stands: waiting for an answer, or answered — approved, rejected, or expired
|
|
21
|
+
* before anyone answered it.
|
|
22
|
+
* @typedef {'pending'|'approved'|'rejected'|'expired'} ApprovalStatus
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Whether Reject asks why: `'optional'` asks and accepts no answer, `'required'` will not reject
|
|
27
|
+
* without one, and `'none'` rejects at once.
|
|
28
|
+
* @typedef {'optional'|'required'|'none'} ApprovalReasonMode
|
|
29
|
+
*/
|
|
30
|
+
|
|
31
|
+
/** @typedef {'approve'|'edit'|'reject'} ApprovalAction */
|
|
32
|
+
|
|
33
|
+
/** @typedef {'slate'|'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'} ApprovalTone */
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* What the request will produce, shown behind a disclosure: the email as it will be sent, the
|
|
37
|
+
* records as they will be written.
|
|
38
|
+
* @typedef {Object} ApprovalPreview
|
|
39
|
+
* @property {string} [label] Text of the disclosure button; "Preview" when absent.
|
|
40
|
+
* @property {Node|Block[]} [content] What the disclosure shows: a node, or blocks.
|
|
41
|
+
* @property {Block[]} [blocks] The same as `content` given as blocks, as the thread model spells it.
|
|
42
|
+
*/
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* @typedef {Object} ApprovalCardOptions
|
|
46
|
+
* @property {string} [title=''] What the agent wants to do, as a question: "Send 3 payment reminders?".
|
|
47
|
+
* @property {string} [description=''] One line under the title: what follows from approving.
|
|
48
|
+
* @property {string|null} [icon=null] Icon name for the tile beside the title; none when null.
|
|
49
|
+
* @property {ApprovalTone} [tone='blue'] Categorical tone of the icon tile.
|
|
50
|
+
* @property {2|3|4|5|6} [headingLevel=3] Element level of the title heading.
|
|
51
|
+
* @property {ApprovalStatus} [status='pending'] Where the request stands.
|
|
52
|
+
* @property {Node|Block[]|null} [details=null] What will happen — recipients, amounts, records —
|
|
53
|
+
* as a node the application built, or as blocks. Model text in blocks is drawn as text only.
|
|
54
|
+
* @property {ApprovalPreview|null} [preview=null] What the request produces, behind a disclosure.
|
|
55
|
+
* @property {Record<string, FieldOptions>|null} [fields=null] The Edit form, keyed by value name.
|
|
56
|
+
* No fields, no Edit.
|
|
57
|
+
* @property {Record<string, unknown>} [values={}] The values the request carries; the Edit form
|
|
58
|
+
* starts from them and `approve` reports them.
|
|
59
|
+
* @property {string|null} [confirmText=null] Text the person must type before Approve goes
|
|
60
|
+
* through, for an action that cannot be undone. Decided by the application from the tool the
|
|
61
|
+
* action triggers, never taken from model output.
|
|
62
|
+
* @property {ApprovalReasonMode} [reason='optional'] Whether Reject asks why.
|
|
63
|
+
* @property {boolean} [edited=false] Whether the values were already edited, for a request
|
|
64
|
+
* restored from a record. Without `editedKeys` every field is listed under "Edited by you".
|
|
65
|
+
* @property {string[]|null} [editedKeys=null] Which values were edited: only these fields are
|
|
66
|
+
* listed under "Edited by you", in field order. A non-empty list implies `edited`; null lists
|
|
67
|
+
* every field of an edited request.
|
|
68
|
+
* @property {string|null} [rejectReason=null] The reason a rejected request was given, for a
|
|
69
|
+
* request restored from a record.
|
|
70
|
+
* @property {string|null} [answeredBy=null] Who answers, as the verdict names them; the message
|
|
71
|
+
* `approvalCard.you` ("you") when null.
|
|
72
|
+
* @property {string|Date|null} [answeredAt=null] When an answered request was answered: a local
|
|
73
|
+
* ISO date-time or a Date. An answer given on the card takes the time it was given.
|
|
74
|
+
* @property {(() => Date)|null} [now=null] The clock: decides whether `answeredAt` is today (the
|
|
75
|
+
* time alone) or another day (date and time), and gives the time of an answer recorded without
|
|
76
|
+
* an explicit `at`. Real time when null.
|
|
77
|
+
* @property {boolean} [keys=true] Whether A, E, and R act while focus is inside the pending card.
|
|
78
|
+
* `handleKey()` works either way.
|
|
79
|
+
* @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
|
|
80
|
+
* @property {(event: CustomEvent<{values: Record<string, unknown>}>) => void} [onapprove] Approve listener.
|
|
81
|
+
* @property {(event: CustomEvent<ApprovalEditDetail>) => void} [onedit] Edit listener.
|
|
82
|
+
* @property {(event: CustomEvent<{reason: string}>) => void} [onreject] Reject listener.
|
|
83
|
+
*/
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* What `update()` changes: any of these options, the rest staying as they are. The status goes
|
|
87
|
+
* through `setStatus()`.
|
|
88
|
+
* @typedef {Pick<ApprovalCardOptions, 'title'|'description'|'icon'|'tone'|'details'|'preview'
|
|
89
|
+
* |'fields'|'values'|'confirmText'|'reason'|'edited'|'editedKeys'>} ApprovalCardUpdate
|
|
90
|
+
*/
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* What a saved edit reports.
|
|
94
|
+
* @typedef {Object} ApprovalEditDetail
|
|
95
|
+
* @property {Record<string, unknown>} values The values as saved, edits included.
|
|
96
|
+
* @property {string[]} changed The fields this save changed against the values before it, in
|
|
97
|
+
* field order; empty when the form was saved unchanged.
|
|
98
|
+
* @property {string[]|null} editedKeys Every field edited so far, this save included: what the
|
|
99
|
+
* card lists under "Edited by you" unless the edit is prevented. Null when the card lists every
|
|
100
|
+
* field (`edited: true` with no `editedKeys`).
|
|
101
|
+
*/
|
|
102
|
+
|
|
103
|
+
const MESSAGES = Object.freeze({
|
|
104
|
+
'approvalCard.approve': 'Approve',
|
|
105
|
+
'approvalCard.edit': 'Edit',
|
|
106
|
+
'approvalCard.reject': 'Reject',
|
|
107
|
+
'approvalCard.you': 'you',
|
|
108
|
+
'approvalCard.status.pending': 'Waiting for you',
|
|
109
|
+
'approvalCard.status.approved': 'Approved',
|
|
110
|
+
'approvalCard.status.rejected': 'Rejected',
|
|
111
|
+
'approvalCard.status.expired': 'Expired',
|
|
112
|
+
'approvalCard.paused': 'The run is paused until you answer.',
|
|
113
|
+
'approvalCard.approvedBy': 'Approved by %1 at %2',
|
|
114
|
+
'approvalCard.approvedByUndated': 'Approved by %1',
|
|
115
|
+
'approvalCard.rejectedBy': 'Rejected by %1 at %2',
|
|
116
|
+
'approvalCard.rejectedByUndated': 'Rejected by %1',
|
|
117
|
+
'approvalCard.expiredAt': 'Expired at %1',
|
|
118
|
+
'approvalCard.expiredUndated': 'Expired without an answer',
|
|
119
|
+
'approvalCard.editedBy': 'Edited by %1',
|
|
120
|
+
'approvalCard.reason': 'Reason',
|
|
121
|
+
'approvalCard.preview': 'Preview',
|
|
122
|
+
'approvalCard.editTitle': 'Edit the request',
|
|
123
|
+
'approvalCard.save': 'Save changes',
|
|
124
|
+
'approvalCard.cancel': 'Cancel',
|
|
125
|
+
'approvalCard.required': 'Fill this in to save.',
|
|
126
|
+
'approvalCard.rejectTitle': 'Reject the request?',
|
|
127
|
+
'approvalCard.reasonLabel': 'Why not?',
|
|
128
|
+
'approvalCard.reasonOptional': 'Optional. Your reason stays with the request.',
|
|
129
|
+
'approvalCard.reasonRequired': 'Your reason stays with the request.',
|
|
130
|
+
'approvalCard.reasonMissing': 'Say why, so the agent can do better next time.'
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Which run state draws each request status: its glyph and tone come from `STATUS`, so a waiting
|
|
135
|
+
* request looks like a waiting step.
|
|
136
|
+
* @type {Readonly<Record<ApprovalStatus, import('../../internal/agent-model.js').RunState>>}
|
|
137
|
+
*/
|
|
138
|
+
export const APPROVAL_STATES = Object.freeze({
|
|
139
|
+
pending: 'waiting',
|
|
140
|
+
approved: 'done',
|
|
141
|
+
rejected: 'skipped',
|
|
142
|
+
expired: 'stopped'
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* The message key of each status's word.
|
|
147
|
+
* @type {Readonly<Record<ApprovalStatus, string>>}
|
|
148
|
+
*/
|
|
149
|
+
const STATUS_WORDS = Object.freeze({
|
|
150
|
+
pending: 'approvalCard.status.pending',
|
|
151
|
+
approved: 'approvalCard.status.approved',
|
|
152
|
+
rejected: 'approvalCard.status.rejected',
|
|
153
|
+
expired: 'approvalCard.status.expired'
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
/** The letter of each action key. */
|
|
157
|
+
const ACTION_KEYS = Object.freeze({ a: 'approve', e: 'edit', r: 'reject' });
|
|
158
|
+
|
|
159
|
+
/** The tones an icon tile may take. */
|
|
160
|
+
const TONES = Object.freeze(['slate', 'blue', 'teal', 'green', 'amber', 'orange', 'red', 'pink', 'violet']);
|
|
161
|
+
|
|
162
|
+
/** What an empty value reads as in the list of edited values. */
|
|
163
|
+
const EMPTY_VALUE = '—';
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* A request that holds an agent's run until a person answers it: what the agent wants to do, what
|
|
167
|
+
* will happen, what it will produce, and Approve, Edit, and Reject. Answered, it freezes into the
|
|
168
|
+
* record of what was decided, by whom, and when.
|
|
169
|
+
*
|
|
170
|
+
* The card never acts on its own: it emits the answer, and the application carries it out. Every
|
|
171
|
+
* answer is preventable, so the application can refuse or defer one and settle the card later
|
|
172
|
+
* through `setStatus()`. A request the agent revises while it waits changes in place through
|
|
173
|
+
* `update()`, which keeps focus where it was.
|
|
174
|
+
*
|
|
175
|
+
* A, E, and R act while focus is inside a pending card and not in a text control; the card never
|
|
176
|
+
* listens to the document. An application that wants the keys from elsewhere forwards them to
|
|
177
|
+
* `handleKey()`.
|
|
178
|
+
*
|
|
179
|
+
* @fires ApprovalCard#approve
|
|
180
|
+
* @fires ApprovalCard#edit
|
|
181
|
+
* @fires ApprovalCard#reject
|
|
182
|
+
* @extends {Component<ApprovalCardOptions>}
|
|
183
|
+
*/
|
|
184
|
+
export class ApprovalCard extends Component {
|
|
185
|
+
static cssName = 'approval-card';
|
|
186
|
+
|
|
187
|
+
/** @type {Readonly<ApprovalCardOptions>} */
|
|
188
|
+
static defaults = {
|
|
189
|
+
title: '',
|
|
190
|
+
description: '',
|
|
191
|
+
icon: null,
|
|
192
|
+
tone: 'blue',
|
|
193
|
+
headingLevel: 3,
|
|
194
|
+
status: 'pending',
|
|
195
|
+
details: null,
|
|
196
|
+
preview: null,
|
|
197
|
+
fields: null,
|
|
198
|
+
values: {},
|
|
199
|
+
confirmText: null,
|
|
200
|
+
reason: 'optional',
|
|
201
|
+
edited: false,
|
|
202
|
+
editedKeys: null,
|
|
203
|
+
rejectReason: null,
|
|
204
|
+
answeredBy: null,
|
|
205
|
+
answeredAt: null,
|
|
206
|
+
now: null,
|
|
207
|
+
keys: true,
|
|
208
|
+
msg: MESSAGES
|
|
209
|
+
};
|
|
210
|
+
|
|
211
|
+
/** @returns {HTMLElement} */
|
|
212
|
+
render() {
|
|
213
|
+
const created = !this.el;
|
|
214
|
+
const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
|
|
215
|
+
this.el = root;
|
|
216
|
+
/** @type {import('../../core/dom.js').TargetSnapshot|null} */
|
|
217
|
+
this._original = created ? null : snapshotTarget(root);
|
|
218
|
+
if (!created) root.replaceChildren();
|
|
219
|
+
this._destroyed = false;
|
|
220
|
+
|
|
221
|
+
const options = this.options;
|
|
222
|
+
/** @type {ApprovalStatus} */
|
|
223
|
+
this._status = normalizeApprovalStatus(options.status);
|
|
224
|
+
/** @type {Record<string, unknown>} */
|
|
225
|
+
this._values = cloneValues(options.values);
|
|
226
|
+
/** @type {Record<string, FieldOptions>|null} */
|
|
227
|
+
this._fields = editFields(options.fields);
|
|
228
|
+
const edited = editedState(options.edited, options.editedKeys);
|
|
229
|
+
this._edited = edited.edited;
|
|
230
|
+
/** @type {string[]|null} The values listed as edited; null lists every field. */
|
|
231
|
+
this._editedKeys = edited.keys;
|
|
232
|
+
/** @type {(() => Date)|null} */
|
|
233
|
+
this._clock = typeof options.now === 'function' ? options.now : null;
|
|
234
|
+
/** @type {string|null} */
|
|
235
|
+
this._by = textOrNull(options.answeredBy);
|
|
236
|
+
/** @type {Date|null} */
|
|
237
|
+
this._at = this._status === 'pending' ? null : toDate(options.answeredAt);
|
|
238
|
+
/** @type {string|null} */
|
|
239
|
+
this._reason = textOrNull(options.rejectReason);
|
|
240
|
+
/** @type {ApprovalReasonMode} */
|
|
241
|
+
this._reasonMode = normalizeReasonMode(options.reason);
|
|
242
|
+
this._title = String(options.title ?? '');
|
|
243
|
+
this._description = String(options.description ?? '');
|
|
244
|
+
/** @type {string|null} */
|
|
245
|
+
this._icon = textOrNull(options.icon);
|
|
246
|
+
this._tone = normalizeTone(options.tone);
|
|
247
|
+
this._confirmText = confirmTextOf(options.confirmText);
|
|
248
|
+
/** @type {unknown} What `details` was drawn from, to compare an update against. */
|
|
249
|
+
this._details = null;
|
|
250
|
+
/** @type {{label: string, content: unknown}|null} What the preview was drawn from. */
|
|
251
|
+
this._preview = null;
|
|
252
|
+
/** @type {{dialog: Dialog, fieldset: Fieldset, fields: Record<string, FieldOptions>}|null} */
|
|
253
|
+
this._editor = null;
|
|
254
|
+
/** @type {{dialog: Dialog, field: Field, blocked: boolean, mode: ApprovalReasonMode}|null} */
|
|
255
|
+
this._rejecter = null;
|
|
256
|
+
/** @type {Dialog|null} The type-to-confirm dialog while it is open. */
|
|
257
|
+
this._confirm = null;
|
|
258
|
+
this._confirming = false;
|
|
259
|
+
this._keys = options.keys !== false;
|
|
260
|
+
|
|
261
|
+
const titleId = uid('zx-approval-card-title');
|
|
262
|
+
this._descriptionId = uid('zx-approval-card-description');
|
|
263
|
+
const level = Math.min(6, Math.max(2, Math.trunc(Number(options.headingLevel)) || 3));
|
|
264
|
+
this._blockLevel = /** @type {2|3|4|5} */ (Math.min(5, level + 1));
|
|
265
|
+
|
|
266
|
+
root.setAttribute('role', 'group');
|
|
267
|
+
root.setAttribute('aria-labelledby', titleId);
|
|
268
|
+
root.tabIndex = -1;
|
|
269
|
+
|
|
270
|
+
this._titleEl = h(`h${level}`, { class: 'zx-approval-card__title', id: titleId }, this._title);
|
|
271
|
+
this._noteEl = h('p', { class: 'zx-approval-card__note', id: uid('zx-approval-card-note') });
|
|
272
|
+
this._statusEl = h('span', { class: 'zx-approval-card__status' });
|
|
273
|
+
/** @type {HTMLElement|null} */
|
|
274
|
+
this._tileEl = null;
|
|
275
|
+
/** @type {HTMLElement|null} */
|
|
276
|
+
this._descriptionEl = null;
|
|
277
|
+
this._headEl = h('div', { class: 'zx-approval-card__head' },
|
|
278
|
+
h('div', { class: 'zx-approval-card__titles' }, this._titleEl, this._noteEl),
|
|
279
|
+
this._statusEl);
|
|
280
|
+
this._changesEl = h('div', { class: 'zx-approval-card__changes', hidden: true });
|
|
281
|
+
this._reasonEl = h('div', { class: 'zx-approval-card__reason', hidden: true });
|
|
282
|
+
/** @type {HTMLElement|null} */
|
|
283
|
+
this._detailsEl = null;
|
|
284
|
+
/** @type {HTMLElement|null} */
|
|
285
|
+
this._previewEl = null;
|
|
286
|
+
/** @type {HTMLElement|null} */
|
|
287
|
+
this._previewToggle = null;
|
|
288
|
+
/** @type {HTMLElement|null} */
|
|
289
|
+
this._previewLabel = null;
|
|
290
|
+
/** @type {HTMLElement|null} */
|
|
291
|
+
this._previewBody = null;
|
|
292
|
+
|
|
293
|
+
this._approveEl = actionButton('approve', this.msg('approvalCard.approve'), 'A', this._keys, 'primary');
|
|
294
|
+
/** @type {HTMLButtonElement|null} */
|
|
295
|
+
this._editEl = null;
|
|
296
|
+
this._rejectEl = actionButton('reject', this.msg('approvalCard.reject'), 'R', this._keys);
|
|
297
|
+
this._actionsEl = h('div', { class: 'zx-approval-card__actions' }, this._approveEl, this._rejectEl);
|
|
298
|
+
root.append(this._headEl, this._changesEl, this._reasonEl, this._actionsEl);
|
|
299
|
+
|
|
300
|
+
this._drawTile();
|
|
301
|
+
this._drawDescription();
|
|
302
|
+
this._drawDetails(options.details);
|
|
303
|
+
this._drawPreview(previewState(options.preview));
|
|
304
|
+
this._drawEditButton();
|
|
305
|
+
|
|
306
|
+
this.listen(root, 'click', (event) => this._onClick(/** @type {MouseEvent} */ (event)));
|
|
307
|
+
if (this._keys) this.listen(root, 'keydown', (event) => { this.handleKey(/** @type {KeyboardEvent} */ (event)); });
|
|
308
|
+
this._sync();
|
|
309
|
+
return root;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
/**
|
|
313
|
+
* Changes the request in place — the agent revised it, or the record it is drawn from changed —
|
|
314
|
+
* and redraws only what changed. Focus stays where it was; when the element that held it is
|
|
315
|
+
* gone (the Edit button, the preview toggle), the card takes it. Of the card's dialogs only one
|
|
316
|
+
* the change makes meaningless closes: the Edit form when `fields` change, the Reject dialog
|
|
317
|
+
* when `reason` changes, the typed confirmation when `confirmText` changes. An open Edit form
|
|
318
|
+
* stays open over new `values` and saves what the person typed. Emits nothing.
|
|
319
|
+
*
|
|
320
|
+
* `edited` and `editedKeys` follow the options' rules: `edited: true` alone keeps the fields
|
|
321
|
+
* already listed (every field, on a card that was not edited); `edited: false` alone clears the
|
|
322
|
+
* list; a non-empty `editedKeys` marks the card edited.
|
|
323
|
+
* @param {ApprovalCardUpdate} [partial={}] The options to change; the rest stay as they are.
|
|
324
|
+
* @returns {this}
|
|
325
|
+
*/
|
|
326
|
+
update(partial = {}) {
|
|
327
|
+
if (this._destroyed || !partial || typeof partial !== 'object') return this;
|
|
328
|
+
/** @param {keyof ApprovalCardUpdate} key @returns {boolean} */
|
|
329
|
+
const has = (key) => Object.hasOwn(partial, key);
|
|
330
|
+
const root = /** @type {HTMLElement} */ (this.el);
|
|
331
|
+
const doc = root.ownerDocument;
|
|
332
|
+
const held = root.contains(doc.activeElement) || this._dialogOpen();
|
|
333
|
+
let listed = false;
|
|
334
|
+
|
|
335
|
+
if (has('title')) {
|
|
336
|
+
const title = String(partial.title ?? '');
|
|
337
|
+
if (title !== this._title) {
|
|
338
|
+
this._title = title;
|
|
339
|
+
this._titleEl.textContent = title;
|
|
340
|
+
this._confirm?.setTitle(title);
|
|
341
|
+
}
|
|
342
|
+
}
|
|
343
|
+
if (has('description')) {
|
|
344
|
+
const description = String(partial.description ?? '');
|
|
345
|
+
if (description !== this._description) {
|
|
346
|
+
this._description = description;
|
|
347
|
+
this._drawDescription();
|
|
348
|
+
}
|
|
349
|
+
}
|
|
350
|
+
if (has('icon') || has('tone')) {
|
|
351
|
+
const name = has('icon') ? textOrNull(partial.icon) : this._icon;
|
|
352
|
+
const tone = has('tone') ? normalizeTone(partial.tone) : this._tone;
|
|
353
|
+
if (name !== this._icon || tone !== this._tone) {
|
|
354
|
+
this._icon = name;
|
|
355
|
+
this._tone = tone;
|
|
356
|
+
this._drawTile();
|
|
357
|
+
}
|
|
358
|
+
}
|
|
359
|
+
if (has('details') && !sameValue(snapshotContent(partial.details), this._details)) this._drawDetails(partial.details);
|
|
360
|
+
if (has('preview')) {
|
|
361
|
+
const preview = previewState(partial.preview);
|
|
362
|
+
if (!sameValue(preview, this._preview)) this._drawPreview(preview);
|
|
363
|
+
}
|
|
364
|
+
if (has('fields')) {
|
|
365
|
+
const fields = editFields(partial.fields);
|
|
366
|
+
if (!sameValue(fields, this._fields)) {
|
|
367
|
+
this._fields = fields;
|
|
368
|
+
// The open form asks for other values now; the next Edit builds it afresh.
|
|
369
|
+
this._editor?.dialog.close();
|
|
370
|
+
this._drawEditButton();
|
|
371
|
+
listed = true;
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
if (has('values')) {
|
|
375
|
+
const values = cloneValues(partial.values);
|
|
376
|
+
if (!sameValue(values, this._values)) {
|
|
377
|
+
this._values = values;
|
|
378
|
+
listed = true;
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
if (has('confirmText')) {
|
|
382
|
+
const text = confirmTextOf(partial.confirmText);
|
|
383
|
+
if (text !== this._confirmText) {
|
|
384
|
+
this._confirmText = text;
|
|
385
|
+
// What was being typed confirms something else now.
|
|
386
|
+
this._confirm?.close(false);
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
if (has('reason')) {
|
|
390
|
+
const mode = normalizeReasonMode(partial.reason);
|
|
391
|
+
if (mode !== this._reasonMode) {
|
|
392
|
+
this._reasonMode = mode;
|
|
393
|
+
this._rejecter?.dialog.close();
|
|
394
|
+
}
|
|
395
|
+
}
|
|
396
|
+
if (has('edited') || has('editedKeys')) {
|
|
397
|
+
const edited = has('edited') ? Boolean(partial.edited) : this._edited;
|
|
398
|
+
// `edited: true` alone keeps what is listed, and lists every field on a card not yet edited.
|
|
399
|
+
const keys = has('editedKeys') ? partial.editedKeys
|
|
400
|
+
: edited && this._edited ? this._editedKeys : null;
|
|
401
|
+
const next = editedState(edited, keys);
|
|
402
|
+
if (next.edited !== this._edited || !sameValue(next.keys, this._editedKeys)) {
|
|
403
|
+
this._edited = next.edited;
|
|
404
|
+
this._editedKeys = next.keys;
|
|
405
|
+
listed = true;
|
|
406
|
+
}
|
|
407
|
+
}
|
|
408
|
+
if (listed) this._drawChanges();
|
|
409
|
+
// An element that held focus is gone and no dialog took it: the card keeps it.
|
|
410
|
+
if (held && !this._dialogOpen() && !root.contains(doc.activeElement)) root.focus({ preventScroll: true });
|
|
411
|
+
return this;
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
/**
|
|
415
|
+
* Settles the request from outside: an answer the application received elsewhere, a request
|
|
416
|
+
* that timed out, or a prevented answer the application has now carried out. Emits nothing.
|
|
417
|
+
* @param {ApprovalStatus} status New status.
|
|
418
|
+
* @param {{by?: string|null, at?: string|Date|null, reason?: string|null}} [answer={}] Who answered,
|
|
419
|
+
* when (now, by the `now` clock, when left out), and the reason a rejection was given.
|
|
420
|
+
* @returns {this}
|
|
421
|
+
*/
|
|
422
|
+
setStatus(status, answer = {}) {
|
|
423
|
+
if (this._destroyed) return this;
|
|
424
|
+
const next = normalizeApprovalStatus(status);
|
|
425
|
+
const changed = next !== this._status;
|
|
426
|
+
this._status = next;
|
|
427
|
+
if (answer && answer.by !== undefined) this._by = textOrNull(answer.by);
|
|
428
|
+
if (answer && answer.reason !== undefined) this._reason = textOrNull(answer.reason);
|
|
429
|
+
if (next === 'pending') {
|
|
430
|
+
this._at = null;
|
|
431
|
+
} else {
|
|
432
|
+
if (answer && answer.at !== undefined) this._at = toDate(answer.at);
|
|
433
|
+
else if (changed || !this._at) this._at = this._now();
|
|
434
|
+
this._closeDialogs();
|
|
435
|
+
}
|
|
436
|
+
this._sync();
|
|
437
|
+
return this;
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
/** @returns {ApprovalStatus} Where the request stands. */
|
|
441
|
+
getStatus() {
|
|
442
|
+
return this._status;
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
/** @returns {Record<string, unknown>} A copy of the values, edits included. */
|
|
446
|
+
getValues() {
|
|
447
|
+
return cloneValues(this._values);
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/**
|
|
451
|
+
* @returns {string[]|null} The fields listed under "Edited by you", in field order: empty when
|
|
452
|
+
* the request was not edited, null when every field is listed.
|
|
453
|
+
*/
|
|
454
|
+
getEditedKeys() {
|
|
455
|
+
if (!this._edited) return [];
|
|
456
|
+
return this._editedKeys ? [...this._editedKeys] : null;
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
/**
|
|
460
|
+
* Moves focus to the card, so a thread can bring the reader to a request when a run starts
|
|
461
|
+
* waiting on it.
|
|
462
|
+
* @param {FocusOptions} [options] Native focus options.
|
|
463
|
+
* @returns {this}
|
|
464
|
+
*/
|
|
465
|
+
focus(options) {
|
|
466
|
+
/** @type {HTMLElement} */ (this.el).focus(options);
|
|
467
|
+
return this;
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
/**
|
|
471
|
+
* Answers a key: A approves, E edits, R rejects. Acts only while the request is pending, never
|
|
472
|
+
* from a text control or with a modifier held, and never while one of the card's dialogs is
|
|
473
|
+
* open. The card calls it for keys inside itself; an application may forward keys from
|
|
474
|
+
* elsewhere.
|
|
475
|
+
* @param {KeyboardEvent} event Key event.
|
|
476
|
+
* @returns {boolean} Whether the key was used; a used key has its default prevented.
|
|
477
|
+
*/
|
|
478
|
+
handleKey(event) {
|
|
479
|
+
if (this._destroyed || !event || this._busy()) return false;
|
|
480
|
+
const target = event.target instanceof Element ? event.target : null;
|
|
481
|
+
// A key from inside a dialog — one of the card's, or any other — is that dialog's.
|
|
482
|
+
const dialog = target?.closest('dialog') ?? null;
|
|
483
|
+
if (dialog && !dialog.contains(this.el)) return false;
|
|
484
|
+
// A card nested in another card's details answers its own keys.
|
|
485
|
+
const owner = target?.closest('.zx-approval-card') ?? null;
|
|
486
|
+
if (owner && owner !== this.el && this.el.contains(owner)) return false;
|
|
487
|
+
const action = approvalKeyAction(event, {
|
|
488
|
+
status: this._status,
|
|
489
|
+
canEdit: Boolean(this._fields),
|
|
490
|
+
editable: isEditableTarget(target)
|
|
491
|
+
});
|
|
492
|
+
if (!action) return false;
|
|
493
|
+
event.preventDefault();
|
|
494
|
+
this._run(action);
|
|
495
|
+
return true;
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
/** @returns {void} */
|
|
499
|
+
destroy() {
|
|
500
|
+
if (this._destroyed) return;
|
|
501
|
+
this._destroyed = true;
|
|
502
|
+
this._confirm?.destroy();
|
|
503
|
+
this._confirm = null;
|
|
504
|
+
if (this._editor) {
|
|
505
|
+
this._editor.fieldset.destroy();
|
|
506
|
+
this._editor.dialog.destroy();
|
|
507
|
+
this._editor = null;
|
|
508
|
+
}
|
|
509
|
+
if (this._rejecter) {
|
|
510
|
+
this._rejecter.field.destroy();
|
|
511
|
+
this._rejecter.dialog.destroy();
|
|
512
|
+
this._rejecter = null;
|
|
513
|
+
}
|
|
514
|
+
super.destroy();
|
|
515
|
+
if (this._original) restoreTarget(this.el, this._original);
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
/** @private @returns {boolean} Whether one of the card's dialogs is open or opening. */
|
|
519
|
+
_busy() {
|
|
520
|
+
return this._confirming || this._dialogOpen();
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
/** @private @returns {boolean} Whether one of the card's dialogs is open. */
|
|
524
|
+
_dialogOpen() {
|
|
525
|
+
return Boolean(this._confirm?.isOpen())
|
|
526
|
+
|| Boolean(this._editor?.dialog.isOpen())
|
|
527
|
+
|| Boolean(this._rejecter?.dialog.isOpen());
|
|
528
|
+
}
|
|
529
|
+
|
|
530
|
+
/** @private @returns {Date} Now, by the `now` clock when there is one. */
|
|
531
|
+
_now() {
|
|
532
|
+
return (this._clock ? toDate(this._clock()) : null) ?? new Date();
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
/** @private @param {MouseEvent} event @returns {void} */
|
|
536
|
+
_onClick(event) {
|
|
537
|
+
const target = event.target instanceof Element ? event.target : null;
|
|
538
|
+
const control = /** @type {HTMLElement|null} */ (target?.closest('[data-approval-action]') ?? null);
|
|
539
|
+
if (!control || control.closest('.zx-approval-card') !== this.el) return;
|
|
540
|
+
const action = control.dataset.approvalAction;
|
|
541
|
+
if (action === 'preview') this._togglePreview();
|
|
542
|
+
else if (action === 'approve' || action === 'edit' || action === 'reject') this._run(action);
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
/** @private @param {ApprovalAction} action @returns {void} */
|
|
546
|
+
_run(action) {
|
|
547
|
+
if (action === 'approve') void this._requestApprove();
|
|
548
|
+
else if (action === 'edit') this._openEdit();
|
|
549
|
+
else this._requestReject();
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
/** @private @returns {void} */
|
|
553
|
+
_togglePreview() {
|
|
554
|
+
if (!this._previewToggle || !this._previewBody) return;
|
|
555
|
+
const open = this._previewToggle.getAttribute('aria-expanded') !== 'true';
|
|
556
|
+
this._previewToggle.setAttribute('aria-expanded', String(open));
|
|
557
|
+
this._previewBody.hidden = !open;
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
/**
|
|
561
|
+
* Approves, after the typed confirmation when the request asks for one.
|
|
562
|
+
* @private
|
|
563
|
+
* @returns {Promise<void>}
|
|
564
|
+
*/
|
|
565
|
+
async _requestApprove() {
|
|
566
|
+
if (this._status !== 'pending' || this._busy()) return;
|
|
567
|
+
const expected = this._confirmText;
|
|
568
|
+
if (expected) {
|
|
569
|
+
this._confirming = true;
|
|
570
|
+
const doc = this.el.ownerDocument;
|
|
571
|
+
const before = new Set(doc.querySelectorAll('dialog'));
|
|
572
|
+
let confirmed = false;
|
|
573
|
+
try {
|
|
574
|
+
const answer = Dialog.confirm({
|
|
575
|
+
title: this._title,
|
|
576
|
+
message: this._description,
|
|
577
|
+
okLabel: this.msg('approvalCard.approve'),
|
|
578
|
+
cancelLabel: this.msg('approvalCard.cancel'),
|
|
579
|
+
danger: true,
|
|
580
|
+
confirmText: expected
|
|
581
|
+
});
|
|
582
|
+
// The confirmation is created and opened synchronously; keep it so destroy() can close it.
|
|
583
|
+
const opened = [...doc.querySelectorAll('dialog')].find((element) => !before.has(element));
|
|
584
|
+
this._confirm = opened ? /** @type {Dialog|null} */ (Dialog.from(opened)) : null;
|
|
585
|
+
confirmed = await answer;
|
|
586
|
+
} finally {
|
|
587
|
+
this._confirming = false;
|
|
588
|
+
this._confirm = null;
|
|
589
|
+
}
|
|
590
|
+
// An update may have changed the text to type while the dialog was open, which closes it.
|
|
591
|
+
if (!confirmed || this._destroyed || this._status !== 'pending' || this._confirmText !== expected) return;
|
|
592
|
+
}
|
|
593
|
+
const event = this.emit('approve', { values: this.getValues() }, { honorDomCancellation: true });
|
|
594
|
+
if (event.defaultPrevented) return;
|
|
595
|
+
this._answer('approved', null);
|
|
596
|
+
}
|
|
597
|
+
|
|
598
|
+
/** @private @returns {void} */
|
|
599
|
+
_openEdit() {
|
|
600
|
+
const fields = this._fields;
|
|
601
|
+
if (this._status !== 'pending' || !fields || this._busy()) return;
|
|
602
|
+
const editor = this._editor ?? this._buildEditor(fields);
|
|
603
|
+
if (editor.fields !== fields) {
|
|
604
|
+
// The fields changed since the form was built: the same dialog takes a new form.
|
|
605
|
+
const fieldset = editForm(fields);
|
|
606
|
+
editor.fieldset.destroy();
|
|
607
|
+
editor.dialog.setContent(fieldset.el);
|
|
608
|
+
editor.fieldset = fieldset;
|
|
609
|
+
editor.fields = fields;
|
|
610
|
+
}
|
|
611
|
+
editor.fieldset.reset();
|
|
612
|
+
editor.fieldset.clearHighlights();
|
|
613
|
+
editor.fieldset.setValues(this._values, { silent: true });
|
|
614
|
+
editor.dialog.open();
|
|
615
|
+
const first = Object.keys(fields)[0];
|
|
616
|
+
// After the dialog's own initial focus, which lands on its close button.
|
|
617
|
+
queueMicrotask(() => {
|
|
618
|
+
if (!this._destroyed && editor.dialog.isOpen()) editor.fieldset.focus(first);
|
|
619
|
+
});
|
|
620
|
+
}
|
|
621
|
+
|
|
622
|
+
/**
|
|
623
|
+
* The Edit dialog, built the first time it is needed.
|
|
624
|
+
* @private
|
|
625
|
+
* @param {Record<string, FieldOptions>} fields
|
|
626
|
+
* @returns {{dialog: Dialog, fieldset: Fieldset, fields: Record<string, FieldOptions>}}
|
|
627
|
+
*/
|
|
628
|
+
_buildEditor(fields) {
|
|
629
|
+
const fieldset = editForm(fields);
|
|
630
|
+
const dialog = new Dialog(null, {
|
|
631
|
+
title: this.msg('approvalCard.editTitle'),
|
|
632
|
+
size: 'md',
|
|
633
|
+
scope: this.el,
|
|
634
|
+
content: fieldset.el,
|
|
635
|
+
buttons: [
|
|
636
|
+
{ label: this.msg('approvalCard.cancel'), action: 'cancel' },
|
|
637
|
+
{ label: this.msg('approvalCard.save'), kind: 'primary', action: () => this._saveEdit() }
|
|
638
|
+
]
|
|
639
|
+
});
|
|
640
|
+
this.listen(dialog.el, 'keydown', (event) => {
|
|
641
|
+
if (isSubmitKey(/** @type {KeyboardEvent} */ (event))) {
|
|
642
|
+
event.preventDefault();
|
|
643
|
+
this._saveEdit();
|
|
644
|
+
}
|
|
645
|
+
});
|
|
646
|
+
this._editor = { dialog, fieldset, fields };
|
|
647
|
+
return this._editor;
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
/** @private @returns {void} */
|
|
651
|
+
_saveEdit() {
|
|
652
|
+
const editor = this._editor;
|
|
653
|
+
const fields = this._fields;
|
|
654
|
+
if (!editor || !fields || editor.fields !== fields || this._status !== 'pending') return;
|
|
655
|
+
const entered = editor.fieldset.getValues();
|
|
656
|
+
const missing = Object.keys(fields).filter((key) => fields[key]?.required && isEmptyValue(entered[key]));
|
|
657
|
+
if (missing.length) {
|
|
658
|
+
editor.fieldset.setHighlights(Object.fromEntries(missing.map((key) => [key, this.msg('approvalCard.required')])));
|
|
659
|
+
editor.fieldset.focus(missing[0]);
|
|
660
|
+
return;
|
|
661
|
+
}
|
|
662
|
+
const values = { ...this._values, ...entered };
|
|
663
|
+
const changed = changedKeys(fields, this._values, values);
|
|
664
|
+
const editedKeys = mergeEditedKeys(this._edited ? this._editedKeys : [], changed, fields);
|
|
665
|
+
const event = this.emit('edit', {
|
|
666
|
+
values: cloneValues(values),
|
|
667
|
+
changed: [...changed],
|
|
668
|
+
editedKeys: editedKeys ? [...editedKeys] : null
|
|
669
|
+
}, { honorDomCancellation: true });
|
|
670
|
+
editor.dialog.close();
|
|
671
|
+
if (event.defaultPrevented) return;
|
|
672
|
+
this._values = values;
|
|
673
|
+
this._edited = true;
|
|
674
|
+
this._editedKeys = editedKeys;
|
|
675
|
+
this._drawChanges();
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
/** @private @returns {void} */
|
|
679
|
+
_requestReject() {
|
|
680
|
+
if (this._status !== 'pending' || this._busy()) return;
|
|
681
|
+
if (this._reasonMode === 'none') {
|
|
682
|
+
this._commitReject('');
|
|
683
|
+
return;
|
|
684
|
+
}
|
|
685
|
+
const rejecter = this._rejecter ?? this._buildRejecter();
|
|
686
|
+
if (rejecter.mode !== this._reasonMode) {
|
|
687
|
+
// The reason became required or optional since the dialog was built: it takes a new field.
|
|
688
|
+
const field = this._reasonField();
|
|
689
|
+
rejecter.field.destroy();
|
|
690
|
+
rejecter.dialog.setContent(field.el);
|
|
691
|
+
rejecter.field = field;
|
|
692
|
+
rejecter.mode = this._reasonMode;
|
|
693
|
+
}
|
|
694
|
+
rejecter.field.setValue('', { silent: true });
|
|
695
|
+
rejecter.field.clearHighlight();
|
|
696
|
+
this._syncRejectButton();
|
|
697
|
+
rejecter.dialog.open();
|
|
698
|
+
queueMicrotask(() => {
|
|
699
|
+
if (!this._destroyed && rejecter.dialog.isOpen()) rejecter.field.focus();
|
|
700
|
+
});
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
/**
|
|
704
|
+
* The Reject dialog, built the first time it is needed.
|
|
705
|
+
* @private
|
|
706
|
+
* @returns {{dialog: Dialog, field: Field, blocked: boolean, mode: ApprovalReasonMode}}
|
|
707
|
+
*/
|
|
708
|
+
_buildRejecter() {
|
|
709
|
+
const required = this._reasonMode === 'required';
|
|
710
|
+
const field = this._reasonField();
|
|
711
|
+
const dialog = new Dialog(null, {
|
|
712
|
+
title: this.msg('approvalCard.rejectTitle'),
|
|
713
|
+
size: 'sm',
|
|
714
|
+
scope: this.el,
|
|
715
|
+
content: field.el,
|
|
716
|
+
buttons: this._rejectButtons(required)
|
|
717
|
+
});
|
|
718
|
+
// On the dialog rather than the field, so a field built anew answers too.
|
|
719
|
+
this.listen(dialog.el, 'input', () => this._syncRejectButton());
|
|
720
|
+
this.listen(dialog.el, 'keydown', (event) => {
|
|
721
|
+
if (isSubmitKey(/** @type {KeyboardEvent} */ (event))) {
|
|
722
|
+
event.preventDefault();
|
|
723
|
+
this._confirmReject();
|
|
724
|
+
}
|
|
725
|
+
});
|
|
726
|
+
this._rejecter = { dialog, field, blocked: required, mode: this._reasonMode };
|
|
727
|
+
return this._rejecter;
|
|
728
|
+
}
|
|
729
|
+
|
|
730
|
+
/** @private @returns {Field} The reason textarea, required or optional as the request asks. */
|
|
731
|
+
_reasonField() {
|
|
732
|
+
const required = this._reasonMode === 'required';
|
|
733
|
+
const field = new Field(null, {
|
|
734
|
+
type: 'textarea',
|
|
735
|
+
label: this.msg('approvalCard.reasonLabel'),
|
|
736
|
+
description: this.msg(required ? 'approvalCard.reasonRequired' : 'approvalCard.reasonOptional'),
|
|
737
|
+
required,
|
|
738
|
+
props: { rows: 3 }
|
|
739
|
+
});
|
|
740
|
+
field.el.classList.add('zx-approval-card__reason-field');
|
|
741
|
+
return field;
|
|
742
|
+
}
|
|
743
|
+
|
|
744
|
+
/**
|
|
745
|
+
* @private
|
|
746
|
+
* @param {boolean} blocked Whether Reject is held until a reason is given.
|
|
747
|
+
* @returns {import('../dialog/dialog.js').DialogButton[]}
|
|
748
|
+
*/
|
|
749
|
+
_rejectButtons(blocked) {
|
|
750
|
+
return [
|
|
751
|
+
{ label: this.msg('approvalCard.cancel'), action: 'cancel' },
|
|
752
|
+
{ label: this.msg('approvalCard.reject'), kind: 'danger', disabled: blocked, action: () => this._confirmReject() }
|
|
753
|
+
];
|
|
754
|
+
}
|
|
755
|
+
|
|
756
|
+
/** @private @returns {void} */
|
|
757
|
+
_syncRejectButton() {
|
|
758
|
+
const rejecter = this._rejecter;
|
|
759
|
+
if (!rejecter) return;
|
|
760
|
+
const blocked = this._reasonMode === 'required' && !String(rejecter.field.getValue() ?? '').trim();
|
|
761
|
+
if (blocked === rejecter.blocked) return;
|
|
762
|
+
rejecter.blocked = blocked;
|
|
763
|
+
rejecter.dialog.setButtons(this._rejectButtons(blocked));
|
|
764
|
+
}
|
|
765
|
+
|
|
766
|
+
/** @private @returns {void} */
|
|
767
|
+
_confirmReject() {
|
|
768
|
+
const rejecter = this._rejecter;
|
|
769
|
+
if (!rejecter || this._status !== 'pending' || this._reasonMode === 'none') return;
|
|
770
|
+
const text = String(rejecter.field.getValue() ?? '').trim();
|
|
771
|
+
if (this._reasonMode === 'required' && !text) {
|
|
772
|
+
rejecter.field.setHighlight(this.msg('approvalCard.reasonMissing'), 'danger');
|
|
773
|
+
rejecter.field.focus();
|
|
774
|
+
return;
|
|
775
|
+
}
|
|
776
|
+
rejecter.dialog.close();
|
|
777
|
+
this._commitReject(text);
|
|
778
|
+
}
|
|
779
|
+
|
|
780
|
+
/** @private @param {string} reason @returns {void} */
|
|
781
|
+
_commitReject(reason) {
|
|
782
|
+
const event = this.emit('reject', { reason }, { honorDomCancellation: true });
|
|
783
|
+
if (event.defaultPrevented) return;
|
|
784
|
+
this._answer('rejected', reason || null);
|
|
785
|
+
}
|
|
786
|
+
|
|
787
|
+
/**
|
|
788
|
+
* Freezes the card into its record, answered now by whoever `answeredBy` names.
|
|
789
|
+
* @private
|
|
790
|
+
* @param {'approved'|'rejected'} status
|
|
791
|
+
* @param {string|null} reason
|
|
792
|
+
* @returns {void}
|
|
793
|
+
*/
|
|
794
|
+
_answer(status, reason) {
|
|
795
|
+
this._status = status;
|
|
796
|
+
this._at = this._now();
|
|
797
|
+
this._reason = reason;
|
|
798
|
+
this._closeDialogs();
|
|
799
|
+
this._sync();
|
|
800
|
+
}
|
|
801
|
+
|
|
802
|
+
/** @private @returns {void} */
|
|
803
|
+
_closeDialogs() {
|
|
804
|
+
this._confirm?.close(false);
|
|
805
|
+
this._editor?.dialog.close();
|
|
806
|
+
this._rejecter?.dialog.close();
|
|
807
|
+
}
|
|
808
|
+
|
|
809
|
+
/** @private @returns {string} Who answers, as the verdict names them. */
|
|
810
|
+
_byText() {
|
|
811
|
+
return this._by ?? this.msg('approvalCard.you');
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
/** @private @returns {void} Draws the icon tile, or takes it away when there is no icon. */
|
|
815
|
+
_drawTile() {
|
|
816
|
+
const name = this._icon;
|
|
817
|
+
if (!name) {
|
|
818
|
+
this._tileEl?.remove();
|
|
819
|
+
this._tileEl = null;
|
|
820
|
+
return;
|
|
821
|
+
}
|
|
822
|
+
const tile = this._tileEl ?? h('span', { class: 'zx-approval-card__tile', 'aria-hidden': 'true' });
|
|
823
|
+
tile.dataset.tone = this._tone;
|
|
824
|
+
tile.replaceChildren(icon(name, { size: 14 }));
|
|
825
|
+
if (!this._tileEl) this._headEl.prepend(tile);
|
|
826
|
+
this._tileEl = tile;
|
|
827
|
+
}
|
|
828
|
+
|
|
829
|
+
/** @private @returns {void} Draws the line under the title, and what describes the card. */
|
|
830
|
+
_drawDescription() {
|
|
831
|
+
const text = this._description;
|
|
832
|
+
if (text && !this._descriptionEl) {
|
|
833
|
+
this._descriptionEl = h('p', { class: 'zx-approval-card__description', id: this._descriptionId });
|
|
834
|
+
this._titleEl.after(this._descriptionEl);
|
|
835
|
+
} else if (!text && this._descriptionEl) {
|
|
836
|
+
this._descriptionEl.remove();
|
|
837
|
+
this._descriptionEl = null;
|
|
838
|
+
}
|
|
839
|
+
if (this._descriptionEl) this._descriptionEl.textContent = text;
|
|
840
|
+
this.el.setAttribute('aria-describedby', [text ? this._descriptionId : '', this._noteEl.id].filter(Boolean).join(' '));
|
|
841
|
+
}
|
|
842
|
+
|
|
843
|
+
/** @private @param {unknown} details @returns {void} */
|
|
844
|
+
_drawDetails(details) {
|
|
845
|
+
this._details = snapshotContent(details);
|
|
846
|
+
const node = contentNode(details, this._blockLevel);
|
|
847
|
+
if (!node) {
|
|
848
|
+
this._detailsEl?.remove();
|
|
849
|
+
this._detailsEl = null;
|
|
850
|
+
} else if (this._detailsEl) {
|
|
851
|
+
this._detailsEl.replaceChildren(node);
|
|
852
|
+
} else {
|
|
853
|
+
this._detailsEl = h('div', { class: 'zx-approval-card__details' }, node);
|
|
854
|
+
this._headEl.after(this._detailsEl);
|
|
855
|
+
}
|
|
856
|
+
}
|
|
857
|
+
|
|
858
|
+
/**
|
|
859
|
+
* Draws the preview disclosure, keeping its toggle — and whether it is open — across a change.
|
|
860
|
+
* @private
|
|
861
|
+
* @param {{label: string, content: unknown}|null} preview
|
|
862
|
+
* @returns {void}
|
|
863
|
+
*/
|
|
864
|
+
_drawPreview(preview) {
|
|
865
|
+
const before = this._preview;
|
|
866
|
+
this._preview = preview;
|
|
867
|
+
if (!preview) {
|
|
868
|
+
this._previewEl?.remove();
|
|
869
|
+
this._previewEl = this._previewToggle = this._previewLabel = this._previewBody = null;
|
|
870
|
+
return;
|
|
871
|
+
}
|
|
872
|
+
const fresh = !this._previewEl;
|
|
873
|
+
if (fresh) {
|
|
874
|
+
const bodyId = uid('zx-approval-card-preview');
|
|
875
|
+
this._previewLabel = h('span');
|
|
876
|
+
this._previewToggle = h('button', {
|
|
877
|
+
type: 'button',
|
|
878
|
+
class: 'zx-approval-card__disclosure',
|
|
879
|
+
'aria-expanded': 'false',
|
|
880
|
+
'aria-controls': bodyId,
|
|
881
|
+
dataset: { approvalAction: 'preview' }
|
|
882
|
+
}, icon('chevron-right', { size: 14 }), this._previewLabel);
|
|
883
|
+
this._previewBody = h('div', { class: 'zx-approval-card__preview-body', id: bodyId, hidden: true });
|
|
884
|
+
this._previewEl = h('div', { class: 'zx-approval-card__preview' }, this._previewToggle, this._previewBody);
|
|
885
|
+
this._actionsEl.before(this._previewEl);
|
|
886
|
+
}
|
|
887
|
+
const label = /** @type {HTMLElement} */ (this._previewLabel);
|
|
888
|
+
const body = /** @type {HTMLElement} */ (this._previewBody);
|
|
889
|
+
label.textContent = preview.label || this.msg('approvalCard.preview');
|
|
890
|
+
if (fresh || !sameValue(preview.content, before?.content)) {
|
|
891
|
+
const node = contentNode(preview.content, this._blockLevel);
|
|
892
|
+
body.replaceChildren(...(node ? [node] : []));
|
|
893
|
+
}
|
|
894
|
+
}
|
|
895
|
+
|
|
896
|
+
/** @private @returns {void} Adds the Edit button when there are fields, and takes it away when not. */
|
|
897
|
+
_drawEditButton() {
|
|
898
|
+
if (this._fields && !this._editEl) {
|
|
899
|
+
this._editEl = actionButton('edit', this.msg('approvalCard.edit'), 'E', this._keys);
|
|
900
|
+
this._approveEl.after(this._editEl);
|
|
901
|
+
} else if (!this._fields && this._editEl) {
|
|
902
|
+
this._editEl.remove();
|
|
903
|
+
this._editEl = null;
|
|
904
|
+
}
|
|
905
|
+
}
|
|
906
|
+
|
|
907
|
+
/**
|
|
908
|
+
* Draws everything that follows the status and the edits.
|
|
909
|
+
* @private
|
|
910
|
+
* @returns {void}
|
|
911
|
+
*/
|
|
912
|
+
_sync() {
|
|
913
|
+
this._drawState();
|
|
914
|
+
this._drawChanges();
|
|
915
|
+
}
|
|
916
|
+
|
|
917
|
+
/**
|
|
918
|
+
* Draws what follows the status: the state glyph and word, the line under the title, the
|
|
919
|
+
* reason, and whether the actions show.
|
|
920
|
+
* @private
|
|
921
|
+
* @returns {void}
|
|
922
|
+
*/
|
|
923
|
+
_drawState() {
|
|
924
|
+
const root = /** @type {HTMLElement} */ (this.el);
|
|
925
|
+
const status = this._status;
|
|
926
|
+
root.dataset.state = status;
|
|
927
|
+
|
|
928
|
+
const entry = STATUS[APPROVAL_STATES[status]];
|
|
929
|
+
this._statusEl.replaceChildren(
|
|
930
|
+
statusIcon(entry.status, { tone: /** @type {import('../select/glyphs.js').StatusTone} */ (entry.tone) }),
|
|
931
|
+
h('span', { class: 'zx-approval-card__status-label' }, this.msg(STATUS_WORDS[status])));
|
|
932
|
+
|
|
933
|
+
const verdict = answerVerdict(status, { by: this._byText(), at: this._at, now: this._at ? this._now() : null });
|
|
934
|
+
this._noteEl.textContent = this.msg(verdict.key, ...verdict.args);
|
|
935
|
+
|
|
936
|
+
const reason = status === 'pending' ? null : this._reason;
|
|
937
|
+
this._reasonEl.replaceChildren(...(reason ? [
|
|
938
|
+
h('p', { class: 'zx-approval-card__label' }, this.msg('approvalCard.reason')),
|
|
939
|
+
h('blockquote', { class: 'zx-approval-card__quote' }, reason)
|
|
940
|
+
] : []));
|
|
941
|
+
this._reasonEl.hidden = !reason;
|
|
942
|
+
|
|
943
|
+
const pending = status === 'pending';
|
|
944
|
+
const focused = root.ownerDocument.activeElement;
|
|
945
|
+
const hadFocus = Boolean(focused && this._actionsEl.contains(focused));
|
|
946
|
+
this._actionsEl.hidden = !pending;
|
|
947
|
+
// The button that answered is gone; the card keeps focus rather than dropping it to the page.
|
|
948
|
+
if (hadFocus && !pending) root.focus({ preventScroll: true });
|
|
949
|
+
}
|
|
950
|
+
|
|
951
|
+
/** @private @returns {void} Draws "Edited by you" over the edited values, or nothing. */
|
|
952
|
+
_drawChanges() {
|
|
953
|
+
if (!this._edited) {
|
|
954
|
+
this._changesEl.replaceChildren();
|
|
955
|
+
this._changesEl.hidden = true;
|
|
956
|
+
return;
|
|
957
|
+
}
|
|
958
|
+
const entries = editedEntries(this._fields, this._values, this._editedKeys);
|
|
959
|
+
this._changesEl.replaceChildren(
|
|
960
|
+
h('p', { class: 'zx-approval-card__label' }, this.msg('approvalCard.editedBy', this._byText())),
|
|
961
|
+
entries.length ? h('dl', { class: 'zx-approval-card__values' }, entries.map((item) => h('div', { class: 'zx-approval-card__value' },
|
|
962
|
+
h('dt', { class: 'zx-approval-card__value-label' }, item.label),
|
|
963
|
+
h('dd', { class: 'zx-approval-card__value-text' }, item.text || EMPTY_VALUE)))) : null);
|
|
964
|
+
this._changesEl.hidden = false;
|
|
965
|
+
}
|
|
966
|
+
}
|
|
967
|
+
|
|
968
|
+
/**
|
|
969
|
+
* Fired when Approve goes through: after the typed confirmation when one is asked for.
|
|
970
|
+
* Preventable: a prevented approval leaves the card pending.
|
|
971
|
+
* @event ApprovalCard#approve
|
|
972
|
+
* @type {CustomEvent<{values: Record<string, unknown>}>}
|
|
973
|
+
*/
|
|
974
|
+
/**
|
|
975
|
+
* Fired when the Edit form is saved, with the values as saved, the fields this save changed, and
|
|
976
|
+
* every field edited so far. Preventable: a prevented edit keeps the earlier values and the
|
|
977
|
+
* earlier list of edited fields.
|
|
978
|
+
* @event ApprovalCard#edit
|
|
979
|
+
* @type {CustomEvent<ApprovalEditDetail>}
|
|
980
|
+
*/
|
|
981
|
+
/**
|
|
982
|
+
* Fired when Reject goes through, with the reason given (empty when none was).
|
|
983
|
+
* Preventable: a prevented rejection leaves the card pending.
|
|
984
|
+
* @event ApprovalCard#reject
|
|
985
|
+
* @type {CustomEvent<{reason: string}>}
|
|
986
|
+
*/
|
|
987
|
+
|
|
988
|
+
/* ------------------------------------------------------------------ helpers -- */
|
|
989
|
+
|
|
990
|
+
/**
|
|
991
|
+
* Reads a request status, falling back to `pending` for anything unknown.
|
|
992
|
+
* @param {unknown} status
|
|
993
|
+
* @returns {ApprovalStatus}
|
|
994
|
+
*/
|
|
995
|
+
export function normalizeApprovalStatus(status) {
|
|
996
|
+
return typeof status === 'string' && Object.hasOwn(APPROVAL_STATES, status)
|
|
997
|
+
? /** @type {ApprovalStatus} */ (status)
|
|
998
|
+
: 'pending';
|
|
999
|
+
}
|
|
1000
|
+
|
|
1001
|
+
/**
|
|
1002
|
+
* Reads a reason mode, falling back to `optional`.
|
|
1003
|
+
* @param {unknown} reason
|
|
1004
|
+
* @returns {ApprovalReasonMode}
|
|
1005
|
+
*/
|
|
1006
|
+
export function normalizeReasonMode(reason) {
|
|
1007
|
+
return reason === 'required' || reason === 'none' ? reason : 'optional';
|
|
1008
|
+
}
|
|
1009
|
+
|
|
1010
|
+
/**
|
|
1011
|
+
* The action a key asks for, or null: A approves, E edits (only with an Edit form), R rejects —
|
|
1012
|
+
* on a pending request, outside text controls, with no modifier held, and not while an input
|
|
1013
|
+
* method is composing or the key repeats.
|
|
1014
|
+
* @param {{key?: string, altKey?: boolean, ctrlKey?: boolean, metaKey?: boolean, shiftKey?: boolean,
|
|
1015
|
+
* isComposing?: boolean, repeat?: boolean, defaultPrevented?: boolean}|null|undefined} event Key event.
|
|
1016
|
+
* @param {{status: ApprovalStatus, canEdit?: boolean, editable?: boolean}} state The card's state,
|
|
1017
|
+
* and whether the key came from a text control.
|
|
1018
|
+
* @returns {ApprovalAction|null}
|
|
1019
|
+
*/
|
|
1020
|
+
export function approvalKeyAction(event, state) {
|
|
1021
|
+
if (!event || !state || state.status !== 'pending' || state.editable) return null;
|
|
1022
|
+
if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return null;
|
|
1023
|
+
if (event.isComposing || event.repeat || event.defaultPrevented) return null;
|
|
1024
|
+
const key = typeof event.key === 'string' && event.key.length === 1 ? event.key.toLowerCase() : '';
|
|
1025
|
+
const action = Object.hasOwn(ACTION_KEYS, key) ? ACTION_KEYS[/** @type {keyof typeof ACTION_KEYS} */ (key)] : null;
|
|
1026
|
+
if (action === 'edit' && !state.canEdit) return null;
|
|
1027
|
+
return /** @type {ApprovalAction|null} */ (action);
|
|
1028
|
+
}
|
|
1029
|
+
|
|
1030
|
+
/**
|
|
1031
|
+
* The line under the title: the pause note while pending, otherwise who answered and when.
|
|
1032
|
+
* @param {ApprovalStatus} status
|
|
1033
|
+
* @param {{by?: string, time?: string}} [answer={}] Who answered, and the formatted time.
|
|
1034
|
+
* @returns {{key: string, args: string[]}} Message key and its arguments.
|
|
1035
|
+
*/
|
|
1036
|
+
export function approvalVerdict(status, { by = 'you', time = '' } = {}) {
|
|
1037
|
+
switch (normalizeApprovalStatus(status)) {
|
|
1038
|
+
case 'approved':
|
|
1039
|
+
return time ? { key: 'approvalCard.approvedBy', args: [by, time] } : { key: 'approvalCard.approvedByUndated', args: [by] };
|
|
1040
|
+
case 'rejected':
|
|
1041
|
+
return time ? { key: 'approvalCard.rejectedBy', args: [by, time] } : { key: 'approvalCard.rejectedByUndated', args: [by] };
|
|
1042
|
+
case 'expired':
|
|
1043
|
+
return time ? { key: 'approvalCard.expiredAt', args: [time] } : { key: 'approvalCard.expiredUndated', args: [] };
|
|
1044
|
+
default:
|
|
1045
|
+
return { key: 'approvalCard.paused', args: [] };
|
|
1046
|
+
}
|
|
1047
|
+
}
|
|
1048
|
+
|
|
1049
|
+
/**
|
|
1050
|
+
* The line under the title for a request as it stands, the answer time written against `now`:
|
|
1051
|
+
* the clock alone on the same day, the date as well on another.
|
|
1052
|
+
* @param {ApprovalStatus} status
|
|
1053
|
+
* @param {{by?: string, at?: string|Date|null, now?: Date|null}} [answer={}] Who answered, when,
|
|
1054
|
+
* and the time it is now (real time when null).
|
|
1055
|
+
* @returns {{key: string, args: string[]}} Message key and its arguments.
|
|
1056
|
+
*/
|
|
1057
|
+
export function answerVerdict(status, { by = 'you', at = null, now = null } = {}) {
|
|
1058
|
+
const date = toDate(at);
|
|
1059
|
+
return approvalVerdict(status, { by, time: date ? formatAnsweredAt(date, toDate(now) ?? new Date()) : '' });
|
|
1060
|
+
}
|
|
1061
|
+
|
|
1062
|
+
/**
|
|
1063
|
+
* Reads a list of edited value names: the distinct non-empty strings, in the order given, or
|
|
1064
|
+
* null when it is not a list.
|
|
1065
|
+
* @param {unknown} keys
|
|
1066
|
+
* @returns {string[]|null}
|
|
1067
|
+
*/
|
|
1068
|
+
export function normalizeEditedKeys(keys) {
|
|
1069
|
+
if (!Array.isArray(keys)) return null;
|
|
1070
|
+
return [...new Set(keys.filter((key) => typeof key === 'string' && key !== ''))];
|
|
1071
|
+
}
|
|
1072
|
+
|
|
1073
|
+
/**
|
|
1074
|
+
* Whether a request reads as edited, and which values it lists as edited. A non-empty
|
|
1075
|
+
* `editedKeys` marks it edited; `edited` without a list lists every field.
|
|
1076
|
+
* @param {unknown} edited The `edited` option.
|
|
1077
|
+
* @param {unknown} editedKeys The `editedKeys` option.
|
|
1078
|
+
* @returns {{edited: boolean, keys: string[]|null}} The values to list: null for every field,
|
|
1079
|
+
* empty when the request was not edited.
|
|
1080
|
+
*/
|
|
1081
|
+
export function editedState(edited, editedKeys) {
|
|
1082
|
+
const keys = normalizeEditedKeys(editedKeys);
|
|
1083
|
+
if (keys?.length || edited) return { edited: true, keys };
|
|
1084
|
+
return { edited: false, keys: [] };
|
|
1085
|
+
}
|
|
1086
|
+
|
|
1087
|
+
/**
|
|
1088
|
+
* The fields edited so far once another save is added: the union, in field order, with names
|
|
1089
|
+
* no field has kept at the end. Null — every field — stays null.
|
|
1090
|
+
* @param {string[]|null|undefined} current The fields edited before.
|
|
1091
|
+
* @param {string[]|null|undefined} added The fields the save changed.
|
|
1092
|
+
* @param {Record<string, unknown>|null} [fields=null] The Edit form, for the order.
|
|
1093
|
+
* @returns {string[]|null}
|
|
1094
|
+
*/
|
|
1095
|
+
export function mergeEditedKeys(current, added, fields = null) {
|
|
1096
|
+
if (current === null) return null;
|
|
1097
|
+
return inFieldOrder(normalizeEditedKeys([...(current ?? []), ...(added ?? [])]) ?? [], fields);
|
|
1098
|
+
}
|
|
1099
|
+
|
|
1100
|
+
/**
|
|
1101
|
+
* Whether two option values are the same: equal primitives, dates at the same time, and arrays
|
|
1102
|
+
* and plain objects with the same contents. Anything else — a node, a function — only when it is
|
|
1103
|
+
* the very same object.
|
|
1104
|
+
* @param {unknown} a
|
|
1105
|
+
* @param {unknown} b
|
|
1106
|
+
* @returns {boolean}
|
|
1107
|
+
*/
|
|
1108
|
+
export function sameValue(a, b) {
|
|
1109
|
+
return sameAt(a, b, 0);
|
|
1110
|
+
}
|
|
1111
|
+
|
|
1112
|
+
/**
|
|
1113
|
+
* Reads a time: a Date, a local ISO date-time ("2026-11-03T10:31"), or epoch milliseconds.
|
|
1114
|
+
* @param {unknown} value
|
|
1115
|
+
* @returns {Date|null}
|
|
1116
|
+
*/
|
|
1117
|
+
export function toDate(value) {
|
|
1118
|
+
if (value == null || value === '') return null;
|
|
1119
|
+
const date = value instanceof Date ? new Date(value.getTime())
|
|
1120
|
+
: typeof value === 'number' || typeof value === 'string' ? new Date(value) : null;
|
|
1121
|
+
return date && !Number.isNaN(date.getTime()) ? date : null;
|
|
1122
|
+
}
|
|
1123
|
+
|
|
1124
|
+
/**
|
|
1125
|
+
* How an answer time is written: the clock alone on the day it is read, the day and month within
|
|
1126
|
+
* the year, and the full date before that.
|
|
1127
|
+
* @param {Date} date
|
|
1128
|
+
* @param {Date} [now=new Date()]
|
|
1129
|
+
* @returns {string} A `formatDate()` pattern.
|
|
1130
|
+
*/
|
|
1131
|
+
export function answeredTimeFormat(date, now = new Date()) {
|
|
1132
|
+
if (date.getFullYear() !== now.getFullYear()) return '%e %b %Y, %H:%M';
|
|
1133
|
+
if (date.getMonth() !== now.getMonth() || date.getDate() !== now.getDate()) return '%e %b, %H:%M';
|
|
1134
|
+
return '%H:%M';
|
|
1135
|
+
}
|
|
1136
|
+
|
|
1137
|
+
/**
|
|
1138
|
+
* An answer time as the verdict writes it: "10:31", "2 Nov, 10:31", "2 Nov 2025, 10:31".
|
|
1139
|
+
* @param {Date} date
|
|
1140
|
+
* @param {Date} [now=new Date()]
|
|
1141
|
+
* @returns {string}
|
|
1142
|
+
*/
|
|
1143
|
+
export function formatAnsweredAt(date, now = new Date()) {
|
|
1144
|
+
return formatDate(date, answeredTimeFormat(date, now));
|
|
1145
|
+
}
|
|
1146
|
+
|
|
1147
|
+
/**
|
|
1148
|
+
* Whether a value counts as not given: nothing, blank text, or an empty list.
|
|
1149
|
+
* @param {unknown} value
|
|
1150
|
+
* @returns {boolean}
|
|
1151
|
+
*/
|
|
1152
|
+
export function isEmptyValue(value) {
|
|
1153
|
+
if (value == null) return true;
|
|
1154
|
+
if (typeof value === 'string') return value.trim() === '';
|
|
1155
|
+
return Array.isArray(value) && value.length === 0;
|
|
1156
|
+
}
|
|
1157
|
+
|
|
1158
|
+
/**
|
|
1159
|
+
* The fields whose value differs between two sets of values. Nothing, `undefined`, and empty text
|
|
1160
|
+
* count as the same.
|
|
1161
|
+
* @param {Record<string, unknown>|null} fields
|
|
1162
|
+
* @param {Record<string, unknown>} before
|
|
1163
|
+
* @param {Record<string, unknown>} after
|
|
1164
|
+
* @returns {string[]} Field keys, in field order.
|
|
1165
|
+
*/
|
|
1166
|
+
export function changedKeys(fields, before, after) {
|
|
1167
|
+
return Object.keys(fields ?? {}).filter((key) => comparable(before?.[key]) !== comparable(after?.[key]));
|
|
1168
|
+
}
|
|
1169
|
+
|
|
1170
|
+
/**
|
|
1171
|
+
* A value as the list of edited values shows it. A choice field's option label stands for its
|
|
1172
|
+
* value; a list joins with commas.
|
|
1173
|
+
* @param {unknown} value
|
|
1174
|
+
* @param {{options?: unknown}|null} [field]
|
|
1175
|
+
* @returns {string} The text, or '' for no value.
|
|
1176
|
+
*/
|
|
1177
|
+
export function displayValue(value, field = null) {
|
|
1178
|
+
const options = field?.options;
|
|
1179
|
+
const labels = options && typeof options === 'object' && !Array.isArray(options)
|
|
1180
|
+
? /** @type {Record<string, unknown>} */ (options) : null;
|
|
1181
|
+
/** @param {unknown} item @returns {string} */
|
|
1182
|
+
const label = (item) => (labels && Object.hasOwn(labels, String(item)) ? String(labels[String(item)]) : String(item));
|
|
1183
|
+
if (isEmptyValue(value)) return '';
|
|
1184
|
+
if (Array.isArray(value)) return value.filter((item) => !isEmptyValue(item)).map(label).join(', ');
|
|
1185
|
+
if (value instanceof Date) return Number.isNaN(value.getTime()) ? '' : value.toISOString();
|
|
1186
|
+
if (typeof value === 'object') return JSON.stringify(value);
|
|
1187
|
+
return label(value);
|
|
1188
|
+
}
|
|
1189
|
+
|
|
1190
|
+
/**
|
|
1191
|
+
* The edited values to list: the changed fields when they are known, otherwise every field.
|
|
1192
|
+
* A request restored from a record with no fields lists every value it carries.
|
|
1193
|
+
* @param {Record<string, {label?: string, options?: unknown}>|null} fields
|
|
1194
|
+
* @param {Record<string, unknown>} values
|
|
1195
|
+
* @param {Set<string>|string[]|null} changed The edited values to list; null for every field.
|
|
1196
|
+
* @returns {Array<{key: string, label: string, text: string}>} In field order.
|
|
1197
|
+
*/
|
|
1198
|
+
export function editedEntries(fields, values, changed) {
|
|
1199
|
+
const keys = fields ? Object.keys(fields) : Object.keys(values ?? {});
|
|
1200
|
+
const only = changed == null ? null : new Set(changed);
|
|
1201
|
+
return keys
|
|
1202
|
+
.filter((key) => !only || only.has(key))
|
|
1203
|
+
.map((key) => ({
|
|
1204
|
+
key,
|
|
1205
|
+
label: String(fields?.[key]?.label || key),
|
|
1206
|
+
text: displayValue(values?.[key], fields?.[key] ?? null)
|
|
1207
|
+
}));
|
|
1208
|
+
}
|
|
1209
|
+
|
|
1210
|
+
/**
|
|
1211
|
+
* @param {unknown} a
|
|
1212
|
+
* @param {unknown} b
|
|
1213
|
+
* @param {number} depth How deep the comparison has gone; past 32 levels it gives up as different.
|
|
1214
|
+
* @returns {boolean}
|
|
1215
|
+
*/
|
|
1216
|
+
function sameAt(a, b, depth) {
|
|
1217
|
+
if (Object.is(a, b)) return true;
|
|
1218
|
+
if (depth > 32 || !a || !b || typeof a !== 'object' || typeof b !== 'object') return false;
|
|
1219
|
+
if (a instanceof Date || b instanceof Date) {
|
|
1220
|
+
return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
|
|
1221
|
+
}
|
|
1222
|
+
if (Array.isArray(a) || Array.isArray(b)) {
|
|
1223
|
+
return Array.isArray(a) && Array.isArray(b) && a.length === b.length
|
|
1224
|
+
&& a.every((item, index) => sameAt(item, b[index], depth + 1));
|
|
1225
|
+
}
|
|
1226
|
+
if (!isPlainObject(a) || !isPlainObject(b)) return false;
|
|
1227
|
+
const left = /** @type {Record<string, unknown>} */ (a);
|
|
1228
|
+
const right = /** @type {Record<string, unknown>} */ (b);
|
|
1229
|
+
const keys = Object.keys(left);
|
|
1230
|
+
return keys.length === Object.keys(right).length
|
|
1231
|
+
&& keys.every((key) => Object.hasOwn(right, key) && sameAt(left[key], right[key], depth + 1));
|
|
1232
|
+
}
|
|
1233
|
+
|
|
1234
|
+
/** @param {object} value @returns {boolean} Whether it is a plain object rather than an instance. */
|
|
1235
|
+
function isPlainObject(value) {
|
|
1236
|
+
const proto = Object.getPrototypeOf(value);
|
|
1237
|
+
return proto === Object.prototype || proto === null;
|
|
1238
|
+
}
|
|
1239
|
+
|
|
1240
|
+
/**
|
|
1241
|
+
* Value names in field order, with names no field has kept after them in the order given.
|
|
1242
|
+
* @param {string[]} keys
|
|
1243
|
+
* @param {Record<string, unknown>|null} fields
|
|
1244
|
+
* @returns {string[]}
|
|
1245
|
+
*/
|
|
1246
|
+
function inFieldOrder(keys, fields) {
|
|
1247
|
+
const order = Object.keys(fields ?? {});
|
|
1248
|
+
const listed = new Set(keys);
|
|
1249
|
+
return [...order.filter((key) => listed.has(key)), ...keys.filter((key) => !order.includes(key))];
|
|
1250
|
+
}
|
|
1251
|
+
|
|
1252
|
+
/**
|
|
1253
|
+
* What content was drawn from, kept to compare an update against: a copy of blocks, so a caller
|
|
1254
|
+
* changing its own array later still reads as a change; a node as itself.
|
|
1255
|
+
* @param {unknown} content
|
|
1256
|
+
* @returns {unknown}
|
|
1257
|
+
*/
|
|
1258
|
+
function snapshotContent(content) {
|
|
1259
|
+
if (content == null) return null;
|
|
1260
|
+
if (typeof content !== 'object' || typeof (/** @type {Node} */ (content)).nodeType === 'number') return content;
|
|
1261
|
+
try {
|
|
1262
|
+
return structuredClone(content);
|
|
1263
|
+
} catch {
|
|
1264
|
+
return content;
|
|
1265
|
+
}
|
|
1266
|
+
}
|
|
1267
|
+
|
|
1268
|
+
/**
|
|
1269
|
+
* The preview as the card draws it, or null for none.
|
|
1270
|
+
* @param {unknown} preview
|
|
1271
|
+
* @returns {{label: string, content: unknown}|null}
|
|
1272
|
+
*/
|
|
1273
|
+
function previewState(preview) {
|
|
1274
|
+
if (!preview || typeof preview !== 'object') return null;
|
|
1275
|
+
const value = /** @type {ApprovalPreview} */ (preview);
|
|
1276
|
+
return {
|
|
1277
|
+
label: value.label == null ? '' : String(value.label),
|
|
1278
|
+
content: snapshotContent(value.content ?? value.blocks ?? null)
|
|
1279
|
+
};
|
|
1280
|
+
}
|
|
1281
|
+
|
|
1282
|
+
/** @param {unknown} tone @returns {ApprovalTone} A known tone, blue otherwise. */
|
|
1283
|
+
function normalizeTone(tone) {
|
|
1284
|
+
return TONES.includes(String(tone)) ? /** @type {ApprovalTone} */ (String(tone)) : 'blue';
|
|
1285
|
+
}
|
|
1286
|
+
|
|
1287
|
+
/** @param {unknown} text @returns {string} The text Approve asks for, or '' for none. */
|
|
1288
|
+
function confirmTextOf(text) {
|
|
1289
|
+
return text == null ? '' : String(text).trim();
|
|
1290
|
+
}
|
|
1291
|
+
|
|
1292
|
+
/**
|
|
1293
|
+
* One of the card's action buttons, carrying its action and, with keys on, its key hint.
|
|
1294
|
+
* @param {ApprovalAction} action
|
|
1295
|
+
* @param {string} label
|
|
1296
|
+
* @param {string} letter
|
|
1297
|
+
* @param {boolean} keys Whether the card answers its keys.
|
|
1298
|
+
* @param {'default'|'primary'} [kind='default']
|
|
1299
|
+
* @returns {HTMLButtonElement}
|
|
1300
|
+
*/
|
|
1301
|
+
function actionButton(action, label, letter, keys, kind = 'default') {
|
|
1302
|
+
const control = button({ label, kind, shortcut: keys ? { label: letter, keys: letter } : undefined });
|
|
1303
|
+
control.dataset.approvalAction = action;
|
|
1304
|
+
return control;
|
|
1305
|
+
}
|
|
1306
|
+
|
|
1307
|
+
/**
|
|
1308
|
+
* The Edit form for a set of fields.
|
|
1309
|
+
* @param {Record<string, FieldOptions>} fields
|
|
1310
|
+
* @returns {Fieldset}
|
|
1311
|
+
*/
|
|
1312
|
+
function editForm(fields) {
|
|
1313
|
+
const fieldset = new Fieldset(null, { fields });
|
|
1314
|
+
fieldset.el.classList.add('zx-approval-card__form');
|
|
1315
|
+
return fieldset;
|
|
1316
|
+
}
|
|
1317
|
+
|
|
1318
|
+
/** @param {unknown} value @returns {string} */
|
|
1319
|
+
function comparable(value) {
|
|
1320
|
+
if (value === undefined || value === null || value === '') return 'null';
|
|
1321
|
+
try {
|
|
1322
|
+
return JSON.stringify(value) ?? 'null';
|
|
1323
|
+
} catch {
|
|
1324
|
+
return String(value);
|
|
1325
|
+
}
|
|
1326
|
+
}
|
|
1327
|
+
|
|
1328
|
+
/** @param {unknown} value @returns {string|null} */
|
|
1329
|
+
function textOrNull(value) {
|
|
1330
|
+
return value == null || String(value).trim() === '' ? null : String(value);
|
|
1331
|
+
}
|
|
1332
|
+
|
|
1333
|
+
/**
|
|
1334
|
+
* A copy of the values, so neither the caller's object nor a listener's changes reach the card.
|
|
1335
|
+
* @param {unknown} values
|
|
1336
|
+
* @returns {Record<string, unknown>}
|
|
1337
|
+
*/
|
|
1338
|
+
function cloneValues(values) {
|
|
1339
|
+
if (!values || typeof values !== 'object' || Array.isArray(values)) return {};
|
|
1340
|
+
try {
|
|
1341
|
+
return structuredClone(/** @type {Record<string, unknown>} */ (values));
|
|
1342
|
+
} catch {
|
|
1343
|
+
return { .../** @type {Record<string, unknown>} */ (values) };
|
|
1344
|
+
}
|
|
1345
|
+
}
|
|
1346
|
+
|
|
1347
|
+
/**
|
|
1348
|
+
* The Edit form's fields, or null for no Edit.
|
|
1349
|
+
* @param {unknown} fields
|
|
1350
|
+
* @returns {Record<string, FieldOptions>|null}
|
|
1351
|
+
*/
|
|
1352
|
+
function editFields(fields) {
|
|
1353
|
+
if (!fields || typeof fields !== 'object' || Array.isArray(fields)) return null;
|
|
1354
|
+
return Object.keys(fields).length ? /** @type {Record<string, FieldOptions>} */ (fields) : null;
|
|
1355
|
+
}
|
|
1356
|
+
|
|
1357
|
+
/**
|
|
1358
|
+
* Draws a node or blocks. Blocks are set as interface-sized prose, their text as text only.
|
|
1359
|
+
* @param {unknown} content
|
|
1360
|
+
* @param {2|3|4|5} headingLevel
|
|
1361
|
+
* @returns {Node|null}
|
|
1362
|
+
*/
|
|
1363
|
+
function contentNode(content, headingLevel) {
|
|
1364
|
+
if (content == null) return null;
|
|
1365
|
+
if (Array.isArray(content)) {
|
|
1366
|
+
return h('div', { class: 'zx-prose zx-approval-card__blocks', dataset: { size: 'sm', zxMeasure: 'full' } },
|
|
1367
|
+
renderBlocks(/** @type {Block[]} */ (content), { headingLevel }));
|
|
1368
|
+
}
|
|
1369
|
+
if (typeof content === 'string') return h('p', { class: 'zx-approval-card__text' }, content);
|
|
1370
|
+
if (typeof (/** @type {Node} */ (content)).nodeType === 'number') return /** @type {Node} */ (content);
|
|
1371
|
+
return null;
|
|
1372
|
+
}
|
|
1373
|
+
|
|
1374
|
+
/** @param {KeyboardEvent} event @returns {boolean} Whether the key is Mod+Enter. */
|
|
1375
|
+
function isSubmitKey(event) {
|
|
1376
|
+
return event.key === 'Enter' && (event.metaKey || event.ctrlKey) && !event.isComposing;
|
|
1377
|
+
}
|