@dudousxd/nestjs-catalog-react 0.19.0-preview.0 → 0.20.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/dist/context.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { CallableWorkflowRef, CatalogAuditEvent, CatalogConnection, CatalogConnector, CatalogObjectPage, CatalogQueryRelation, CatalogQueryResult, CatalogRevision, CatalogSearchResult, CatalogSnapshot, CatalogTraceList, CatalogTransform, ConnectionCheck, ConnectorRun, Dashboard, DashboardCard, DeleteReconciliation, LoadExpectation, LoadExpectationInput, ObjectQueryParams, PropertyPatch, ResolvedLoadExpectation, RowCountBound, SaveQueryInput, SavedQuery, SnapshotRef, StoredLoadExpectation, TraceQuery, TransformLanguage, TransformResult, TypePatch } from '@dudousxd/nestjs-catalog/client';
1
+ import type { CallableWorkflowRef, CatalogAuditEvent, CatalogConnection, CatalogConnector, CatalogObjectPage, CatalogQueryRelation, CatalogQueryResult, CatalogRevision, CatalogSearchResult, CatalogSnapshot, CatalogTrace, CatalogTraceList, CatalogTransform, ConnectionCheck, ConnectorRun, Dashboard, DashboardCard, DeleteReconciliation, LoadExpectation, LoadExpectationInput, ObjectQueryParams, PropertyPatch, ResolvedLoadExpectation, RowCountBound, SaveQueryInput, SavedQuery, SnapshotRef, StoredLoadExpectation, TraceQuery, TransformLanguage, TransformResult, TypePatch } from '@dudousxd/nestjs-catalog/client';
2
2
  import { type ReactNode } from 'react';
3
3
  import type { EmbeddedChartPayload, EmbeddedDashboardPayload } from './embed/payload';
4
4
  import { type PeopleQuery } from './routes';
@@ -454,6 +454,15 @@ export interface CatalogClient {
454
454
  * and collapsing the two would cost the first question its answer.
455
455
  */
456
456
  listTraces(query: TraceQuery): Promise<CatalogTraceList>;
457
+ /**
458
+ * One trace, with the event payloads `listTraces` leaves behind.
459
+ *
460
+ * The pair is the point. A list page carries every span of every trace on it,
461
+ * so putting the payloads there means fetching thousands of them to draw
462
+ * waterfalls that read none — see `CatalogTraceSpan.detail`. This is the call
463
+ * that has them, and a screen makes it for the one trace somebody opened.
464
+ */
465
+ getTrace(id: string): Promise<CatalogTrace>;
457
466
  /**
458
467
  * Getting data in.
459
468
  *
package/dist/context.js CHANGED
@@ -51,6 +51,7 @@ export function CatalogProvider({ transport, pipelineBasePath = DEFAULT_PIPELINE
51
51
  embedDashboard: (id) => transport.get(embedRoutes.dashboard(id)),
52
52
  listEvents: (query) => transport.get(catalogRoutes.events(), { ...query }),
53
53
  listTraces: (query) => transport.get(catalogRoutes.traces(), { ...query }),
54
+ getTrace: (id) => transport.get(catalogRoutes.trace(id)),
54
55
  pipelineCapabilities: () => transport.get(pipeline.capabilities()),
55
56
  listCallableWorkflows: () => transport.get(pipeline.callableWorkflows()),
56
57
  listConnections: () => transport.get(pipeline.connections()),
@@ -1,5 +1,5 @@
1
1
  import type { Edge, Node } from '@xyflow/react';
2
- import { type WorkflowEdge, type WorkflowNode, type WorkflowNodeKind, type WorkflowRunNode } from './model';
2
+ import { type WorkflowEdge, type WorkflowFilterPredicate, type WorkflowNode, type WorkflowNodeKind, type WorkflowRunNode } from './model';
3
3
  import { type WorkflowProblem } from './validate';
4
4
  /**
5
5
  * Turning the stored graph into what React Flow draws, and back.
@@ -60,6 +60,29 @@ export interface NodeDescriptions {
60
60
  transformName(id: string | undefined): string | undefined;
61
61
  connectionName(id: string | undefined): string | undefined;
62
62
  }
63
+ /**
64
+ * A predicate as a sentence.
65
+ *
66
+ * Shared by the node's face and by the inspector's summary, so the two cannot
67
+ * describe one filter differently — which on a screen whose whole job is making
68
+ * a drop visible would be worse than describing it badly.
69
+ *
70
+ * Groups are parenthesised whenever they are nested, and never at the top, so
71
+ * the common single-group predicate reads as a list rather than as a formula.
72
+ */
73
+ export declare function describeFilterPredicate(predicate: WorkflowFilterPredicate, nested?: boolean): string;
74
+ /**
75
+ * What a filter did to a run, as a phrase — or nothing, for every other node.
76
+ *
77
+ * Keyed off `rowsIn` being **present** rather than off the node's kind, which is
78
+ * the only check that stays right in both directions: a filter that ran before
79
+ * the server recorded an input count has no drop to report and must not claim
80
+ * one, and no other kind sets the field at all. Subtracting from a defaulted
81
+ * zero would make every historical node read as having dropped its whole output.
82
+ *
83
+ * Exported so the node badge and the aria label say the same sentence.
84
+ */
85
+ export declare function describeDrop(run: WorkflowRunNode): string | undefined;
63
86
  export declare function toFlowNodes(nodes: WorkflowNode[], edges: WorkflowEdge[], describe: NodeDescriptions, problemsFor: Map<string, WorkflowProblem[]>, runFor: Map<string, WorkflowRunNode>): WorkflowFlowNode[];
64
87
  export declare function defaultLabel(kind: WorkflowNodeKind): string;
65
88
  /**
@@ -1,6 +1,6 @@
1
1
  import { WORKFLOW_NODE_HEIGHT, WORKFLOW_NODE_WIDTH, workflowColumnX, workflowRowY, workflowRunOrder, } from '@dudousxd/nestjs-catalog/client';
2
2
  import { MarkerType } from '@xyflow/react';
3
- import { nodeName, unreachableNodeKind, unreachablePredicateKind, } from './model';
3
+ import { nodeName, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, } from './model';
4
4
  import { edgeId } from './validate';
5
5
  /**
6
6
  * Turning the stored graph into what React Flow draws, and back.
@@ -50,11 +50,121 @@ function subtitleFor(node, describe) {
50
50
  return callSubtitle(node);
51
51
  if (node.kind === 'if')
52
52
  return ifSubtitle(node);
53
+ if (node.kind === 'filter')
54
+ return filterSubtitle(node);
53
55
  if (node.kind === 'transform') {
54
56
  return describe.transformName(node.transformId) ?? 'no transform chosen';
55
57
  }
56
58
  return unreachableNodeKind(node, 'subtitleFor');
57
59
  }
60
+ /**
61
+ * How much a node's face will spend on a predicate before summarising it.
62
+ *
63
+ * A node is 224px wide and the subtitle is one truncated line, so a long
64
+ * predicate spelled out in full is an ellipsis and nothing else. Past this many
65
+ * leaves the face says how many conditions there are instead, which at least
66
+ * tells a reader there is something to open.
67
+ */
68
+ const FILTER_FACE_LEAVES = 2;
69
+ /**
70
+ * The test, on the face of the node — the reason this kind exists rather than a
71
+ * transform that returns a subset.
72
+ *
73
+ * "Keep the open orders" readable off the canvas is reason one of three on
74
+ * `WorkflowFilterNode`, so the subtitle is the feature and not decoration. It
75
+ * shows the *values* as well as the columns, which is a difference from
76
+ * `ifSubtitle` and a deliberate one: an if node stores the name of an
77
+ * environment variable and never its contents, because that is where a
78
+ * credential would be, while a filter's value is a business constant somebody
79
+ * typed into the graph and is already visible to anyone who can see the node.
80
+ *
81
+ * The predicate is read into a variable that admits `undefined` before it is
82
+ * narrowed, for the reason `ifSubtitle` gives: this draws whatever a server
83
+ * sent, and a canvas that throws while rendering a node is a screen nobody can
84
+ * use to fix that node.
85
+ */
86
+ function filterSubtitle(node) {
87
+ const predicate = node.predicate;
88
+ if (!predicate)
89
+ return 'nothing to test';
90
+ const leaves = countFilterLeaves(predicate);
91
+ if (leaves > FILTER_FACE_LEAVES)
92
+ return `keeps rows matching ${leaves} conditions`;
93
+ return `keeps ${describeFilterPredicate(predicate)}`;
94
+ }
95
+ /** How many comparisons a predicate is made of, groups not counted. */
96
+ function countFilterLeaves(predicate) {
97
+ if (predicate.kind === 'all' || predicate.kind === 'any') {
98
+ let total = 0;
99
+ for (const child of predicate.children)
100
+ total += countFilterLeaves(child);
101
+ return total;
102
+ }
103
+ return 1;
104
+ }
105
+ /**
106
+ * A predicate as a sentence.
107
+ *
108
+ * Shared by the node's face and by the inspector's summary, so the two cannot
109
+ * describe one filter differently — which on a screen whose whole job is making
110
+ * a drop visible would be worse than describing it badly.
111
+ *
112
+ * Groups are parenthesised whenever they are nested, and never at the top, so
113
+ * the common single-group predicate reads as a list rather than as a formula.
114
+ */
115
+ export function describeFilterPredicate(predicate, nested = false) {
116
+ if (predicate.kind === 'all' || predicate.kind === 'any') {
117
+ const joined = predicate.children
118
+ .map((child) => describeFilterPredicate(child, true))
119
+ .join(predicate.kind === 'all' ? ' and ' : ' or ');
120
+ return nested && predicate.children.length > 1 ? `(${joined})` : joined;
121
+ }
122
+ if (predicate.kind === 'present') {
123
+ return `${predicate.column} ${predicate.operator === 'isNull' ? 'is empty' : 'has a value'}`;
124
+ }
125
+ if (predicate.kind === 'oneOf') {
126
+ const values = predicate.values.map((value) => showFilterValue(value)).join(', ');
127
+ return `${predicate.column} ${predicate.operator === 'in' ? 'is one of' : 'is none of'} ${values}`;
128
+ }
129
+ if (predicate.kind === 'compare') {
130
+ return `${predicate.column} ${FILTER_OPERATOR_WORDS[predicate.operator]} ${showFilterValue(predicate.value)}`;
131
+ }
132
+ return unreachableFilterPredicateKind(predicate, 'describeFilterPredicate');
133
+ }
134
+ /**
135
+ * Each operator as the words a reader of the canvas would use.
136
+ *
137
+ * A `Record` keyed by the operator union, so an operator added to core without a
138
+ * phrase here is a build failure rather than a node whose subtitle silently says
139
+ * `undefined` — the same reason `BRANCH_STYLE` above is a record.
140
+ *
141
+ * Symbols rather than words for the four orderings, because `>` is unambiguous
142
+ * in every locale a column name is written in and "greater than" is three words
143
+ * of a line that has to fit in 224 pixels.
144
+ */
145
+ const FILTER_OPERATOR_WORDS = {
146
+ equals: '=',
147
+ notEquals: '≠',
148
+ greaterThan: '>',
149
+ greaterThanOrEqual: '≥',
150
+ lessThan: '<',
151
+ lessThanOrEqual: '≤',
152
+ contains: 'contains',
153
+ notContains: 'does not contain',
154
+ startsWith: 'starts with',
155
+ notStartsWith: 'does not start with',
156
+ };
157
+ /**
158
+ * One value, quoted only when it is text.
159
+ *
160
+ * `status = "OPEN"` and `qty = 10` are different tests, and the quotes are the
161
+ * only thing on the face that says which — three-valued logic aside, a string
162
+ * `"10"` never equals a number `10` here, and that is exactly the mistake the
163
+ * run log has to report as an incomparable value.
164
+ */
165
+ function showFilterValue(value) {
166
+ return typeof value === 'string' ? `"${value}"` : String(value);
167
+ }
58
168
  /**
59
169
  * The test, on the face of the node.
60
170
  *
@@ -134,12 +244,41 @@ function ariaLabelFor(node, data, incoming, outgoing) {
134
244
  const because = data.run.skippedBecause === 'branch-not-taken'
135
245
  ? ', because it is on the branch that was not taken, so it committed nothing'
136
246
  : '';
137
- parts.push(`last run ${data.run.status}${branch}${because}`);
247
+ // The drop is in the spoken label as well as the tooltip, because a tooltip
248
+ // is a hover and this is the sentence a screen reader user gets instead of
249
+ // the whole canvas. A filter that dropped nine tenths of a load and said so
250
+ // only on hover would be invisible to exactly the reader who cannot check.
251
+ const dropped = describeDrop(data.run);
252
+ parts.push(`last run ${data.run.status}${branch}${because}${dropped ? `, ${dropped}` : ''}`);
138
253
  }
139
254
  for (const problem of data.problems)
140
255
  parts.push(problem.message);
141
256
  return parts.join('. ');
142
257
  }
258
+ /**
259
+ * What a filter did to a run, as a phrase — or nothing, for every other node.
260
+ *
261
+ * Keyed off `rowsIn` being **present** rather than off the node's kind, which is
262
+ * the only check that stays right in both directions: a filter that ran before
263
+ * the server recorded an input count has no drop to report and must not claim
264
+ * one, and no other kind sets the field at all. Subtracting from a defaulted
265
+ * zero would make every historical node read as having dropped its whole output.
266
+ *
267
+ * Exported so the node badge and the aria label say the same sentence.
268
+ */
269
+ export function describeDrop(run) {
270
+ const given = run.rowsIn;
271
+ if (typeof given !== 'number' || typeof run.rows !== 'number')
272
+ return undefined;
273
+ const dropped = given - run.rows;
274
+ if (dropped <= 0)
275
+ return `${given} rows in, none dropped`;
276
+ // The percentage is what makes the number readable: "7,541,187 dropped" needs
277
+ // arithmetic before anybody can tell a working filter from a broken predicate,
278
+ // and "98.7%" does not.
279
+ const share = given === 0 ? 0 : Math.round((dropped / given) * 1000) / 10;
280
+ return `${given} rows in, ${run.rows} out — ${dropped} dropped (${share}%)`;
281
+ }
143
282
  export function toFlowNodes(nodes, edges, describe, problemsFor, runFor) {
144
283
  const labelOf = new Map(nodes.map((node) => [node.id, nodeName(node)]));
145
284
  const names = (ids) => ids.map((id) => labelOf.get(id) ?? id);
@@ -189,6 +328,8 @@ export function defaultLabel(kind) {
189
328
  return 'Call';
190
329
  if (kind === 'if')
191
330
  return 'If';
331
+ if (kind === 'filter')
332
+ return 'Filter';
192
333
  if (kind === 'transform')
193
334
  return 'Transform';
194
335
  return unreachableNodeKind(kind, 'defaultLabel');
@@ -230,6 +371,26 @@ export function toFlowEdges(edges, nodes, brokenEdgeIds, flowing = new Set()) {
230
371
  flowing: flowing.has(edgeId(edge)),
231
372
  }));
232
373
  }
374
+ /**
375
+ * The arrowhead, hoisted out of the edge builder — and this is a bug fix, not tidying.
376
+ *
377
+ * React Flow keeps one `<defs>` of marker definitions, derived from the markers
378
+ * its edges reference. `toFlowEdges` is memoised on `draft.nodes`, so **every
379
+ * frame of a node drag rebuilds the whole edge array**, and a fresh
380
+ * `{ type, width, height }` literal per edge per frame churned that registry:
381
+ * for the instant the defs were being rebuilt, `marker-end="url(#…)"` pointed at
382
+ * nothing. The line survived — it is a `path` — and the arrowhead vanished,
383
+ * which is exactly what somebody dragging a node reported seeing.
384
+ *
385
+ * One frozen object, referenced by every edge, gives the registry a stable
386
+ * identity to dedupe on. Frozen rather than merely `const` because it is now
387
+ * shared by every edge on the canvas, and a mutation would move all of them.
388
+ */
389
+ const ARROW_END = Object.freeze({
390
+ type: MarkerType.ArrowClosed,
391
+ width: 14,
392
+ height: 14,
393
+ });
233
394
  /**
234
395
  * One wire, drawn.
235
396
  *
@@ -256,7 +417,7 @@ function toFlowEdge(edge, context) {
256
417
  animated: context.flowing,
257
418
  // An arrowhead, because "the output of this feeds that" is directional and
258
419
  // a plain line says only that two nodes are related.
259
- markerEnd: { type: MarkerType.ArrowClosed, width: 14, height: 14 },
420
+ markerEnd: ARROW_END,
260
421
  label: edge.branch,
261
422
  labelStyle: branch ? { fill: branch.text, fontSize: 10, fontWeight: 600 } : undefined,
262
423
  // The word sits on the wire, so it takes the canvas behind it rather than a
@@ -0,0 +1,291 @@
1
+ /**
2
+ * Taking an edit back, throwing the whole draft away, and not losing it by
3
+ * accident.
4
+ *
5
+ * WHY THIS IS ITS OWN FILE
6
+ * ------------------------
7
+ * Everything here is about the same one thing — the gap between what is on the
8
+ * canvas and what the server has — and none of it is about drawing a graph.
9
+ * `WorkflowCanvas.tsx` is already six thousand lines and is the file every
10
+ * feature wants to grow, so the rule that keeps it readable is that a concern
11
+ * with its own vocabulary gets its own module. This one has four words in it:
12
+ * an ACTION (the unit undo steps over), the PAST (the actions still takeable
13
+ * back), the BASELINE (the graph as the server last described it) and DIRTY
14
+ * (whether those two differ).
15
+ *
16
+ * WHAT THIS DOES NOT COVER, AND SAYS SO ON SCREEN
17
+ * ----------------------------------------------
18
+ * Undo is about the DRAFT and nothing else. Saving, publishing, running and
19
+ * deleting the workflow are requests the server has already answered; a control
20
+ * that appeared to unmake one of them would be promising something no client
21
+ * can deliver. The boundary is stated in {@link UNDO_SCOPE}, which is rendered —
22
+ * as a tooltip for a pointer and as text for a screen reader — rather than left
23
+ * in this comment, because a boundary somebody has to read the source to learn
24
+ * is not a boundary they will learn.
25
+ *
26
+ * WHY SNAPSHOTS RATHER THAN INVERSE COMMANDS
27
+ * ------------------------------------------
28
+ * The alternative is an undo stack of operations that know how to reverse
29
+ * themselves. That is smaller in memory and considerably more code, and every
30
+ * new gesture on the canvas is a new inverse that can be written wrongly — a
31
+ * wrong inverse is silent, and lands in a SAVED graph. A snapshot cannot be
32
+ * wrong about what the graph was. The cost is bounded by {@link UNDO_DEPTH} and
33
+ * by the fact that a snapshot holds the same node and edge ARRAYS the draft
34
+ * already held: this canvas replaces arrays rather than mutating them (see the
35
+ * copy note in `draftFrom`), so an entry costs four references, not a graph.
36
+ */
37
+ import type { WorkflowEdge, WorkflowNode } from './model';
38
+ /**
39
+ * How many actions can be taken back.
40
+ *
41
+ * A cap rather than an unbounded stack, and 50 rather than 500, because the
42
+ * promise a history makes should be one it can keep at any graph size. Fifty
43
+ * snapshots of a hundred-node graph is fifty times four references — nothing —
44
+ * but the honesty matters more than the arithmetic: an unbounded stack grows
45
+ * with how long somebody has had the tab open, which is exactly the session
46
+ * where they can least afford the tab to get slow.
47
+ *
48
+ * At the limit the OLDEST entry is dropped, so undo always steps back from
49
+ * where the person is rather than refusing. What is lost is the ability to walk
50
+ * all the way to the beginning — and that is what Reset is for, which is why the
51
+ * two controls sit beside each other and why {@link resetDescription} says how
52
+ * many actions are about to go.
53
+ */
54
+ export declare const UNDO_DEPTH = 50;
55
+ /**
56
+ * How long a run of edits stays open, when nothing else closes it.
57
+ *
58
+ * The fallback half of the granularity rule. A gesture with a real end — a drag
59
+ * — says so through `continuing` and ignores this entirely; a gesture without
60
+ * one — typing into a field, holding an arrow key — has only elapsed time to go
61
+ * on. 700ms is longer than a fast typist's inter-key gap and shorter than the
62
+ * pause somebody makes when they stop to think, which is the boundary between
63
+ * "still writing the name" and "wrote the name, then did something else".
64
+ */
65
+ export declare const RUN_WINDOW_MS = 700;
66
+ /** What undo can and cannot reach, in the words the controls use. */
67
+ export declare const UNDO_SCOPE: string;
68
+ /** Said once, when somebody reaches for a redo that deliberately does not exist. */
69
+ export declare const NO_REDO = "There is no redo on this canvas. Undo only steps backwards; Reset returns the whole drawing to the last saved version.";
70
+ /**
71
+ * The part of a draft an edit can change.
72
+ *
73
+ * Deliberately not the whole draft: `id` and `version` are the server's answers
74
+ * about which stored graph this is, and an undo that could change them would be
75
+ * an undo that quietly retargets the next save.
76
+ */
77
+ export interface DraftSnapshot {
78
+ name: string;
79
+ description: string;
80
+ nodes: WorkflowNode[];
81
+ edges: WorkflowEdge[];
82
+ }
83
+ /** One takeable-back action: what the draft was before it, and what to call it. */
84
+ export interface HistoryEntry {
85
+ before: DraftSnapshot;
86
+ /**
87
+ * A past-tense phrase, announced as `Undone: {label}.`
88
+ *
89
+ * Written from the CALLER's vocabulary rather than from the diff, because a
90
+ * label derived from what changed says "two edges removed" where the person
91
+ * pressed "delete Out" — and the whole job of this string is to be recognised
92
+ * by somebody who cannot see what moved.
93
+ */
94
+ label: string;
95
+ /** Consecutive edits sharing a run key fold into this one entry. */
96
+ run?: string;
97
+ at: number;
98
+ }
99
+ /**
100
+ * What an edit says about itself.
101
+ *
102
+ * Every call site passes one. There is no default, on purpose: an unlabelled
103
+ * entry is an undo that announces nothing, and the moment a default exists it is
104
+ * what new call sites get.
105
+ */
106
+ export interface EditAction {
107
+ label: string;
108
+ /**
109
+ * Names the gesture, when this edit is one frame of a longer one. Two edits
110
+ * fold together only when their keys match, so dragging node A and then node B
111
+ * are always two entries even back to back.
112
+ */
113
+ run?: string;
114
+ /**
115
+ * Set while the gesture is demonstrably still happening — a pointer still
116
+ * down. Folds into the open run however long it has been going, which is what
117
+ * keeps a slow drag with a pause in the middle one action rather than two.
118
+ */
119
+ continuing?: boolean;
120
+ }
121
+ /**
122
+ * The draft fields this module owns.
123
+ *
124
+ * Structural rather than an import of `Draft`, which lives in `WorkflowCanvas`
125
+ * and would make this a cycle. The canvas's `Draft` extends it, so the two
126
+ * cannot drift without the compiler saying so.
127
+ */
128
+ export interface HistoricDraft extends DraftSnapshot {
129
+ dirty: boolean;
130
+ /** Oldest first. The last entry is the next undo. */
131
+ past: HistoryEntry[];
132
+ /**
133
+ * The graph as the server last described it: the load, or the most recent
134
+ * save in this session.
135
+ *
136
+ * This is what makes Reset different from undoing to the beginning. Save
137
+ * halfway through a session and the baseline MOVES to that save — so Reset
138
+ * afterwards returns to the saved v2, not to the v1 the tab was opened on.
139
+ * Undoing forty times would walk past that save and back to v1, which is a
140
+ * different and much more surprising thing to hand somebody who asked to throw
141
+ * away their unsaved work.
142
+ */
143
+ baseline: DraftSnapshot;
144
+ }
145
+ export declare function snapshotOf(draft: DraftSnapshot): DraftSnapshot;
146
+ /**
147
+ * Whether two snapshots are the same graph.
148
+ *
149
+ * Reference identity on the arrays, and that is the point rather than a
150
+ * shortcut. Nothing on this canvas mutates a node or an edge array in place —
151
+ * every path replaces — so two identical references ARE the same graph, and the
152
+ * comparison cannot report "unchanged" for a graph that has changed. It can
153
+ * report "changed" for a graph that has been edited back to where it started
154
+ * through two different arrays, and that asymmetry is the safe one: the only
155
+ * consequence is a save button that stays live and a leave-warning that still
156
+ * fires, which is a nuisance. The opposite error loses work.
157
+ *
158
+ * Undo restores the very arrays it recorded, so walking all the way back to the
159
+ * baseline compares equal and the draft goes genuinely clean — which is what
160
+ * makes the beforeunload guard below trustworthy enough to be worth having.
161
+ */
162
+ export declare function sameSnapshot(a: DraftSnapshot, b: DraftSnapshot): boolean;
163
+ /**
164
+ * An edit, recorded.
165
+ *
166
+ * Pure, and it has to be: this runs inside a `setState` updater, which React is
167
+ * free to call twice for the same input. Nothing here reads or writes anything
168
+ * outside its arguments except the clock, and the clock only moves a timestamp
169
+ * that two calls a microsecond apart agree about anyway.
170
+ */
171
+ export declare function withEdit<T extends HistoricDraft>(before: T, after: T, action: EditAction): T;
172
+ /** The next thing undo would take back, for a control that has to name it. */
173
+ export declare function nextUndo(draft: HistoricDraft): HistoryEntry | undefined;
174
+ /**
175
+ * One action back.
176
+ *
177
+ * Returns the label as well as the draft because the announcement is half the
178
+ * feature: undo can revert something that is scrolled off the canvas, and a
179
+ * silent revert of an invisible thing is indistinguishable from nothing
180
+ * happening.
181
+ */
182
+ export declare function undone<T extends HistoricDraft>(draft: T): {
183
+ draft: T;
184
+ label: string;
185
+ } | null;
186
+ /**
187
+ * All the way back to the last saved version.
188
+ *
189
+ * The history goes with it. Keeping it would offer to undo the reset, which is
190
+ * a redo of everything by another name — and this module does not have one.
191
+ */
192
+ export declare function reverted<T extends HistoricDraft>(draft: T): T;
193
+ /** The ids still in the graph, for the per-node bookkeeping the canvas keeps. */
194
+ export declare function keepKnown(ids: ReadonlySet<string>, nodes: WorkflowNode[]): ReadonlySet<string>;
195
+ /** How many nodes, named where naming them is short enough to be useful. */
196
+ export declare function namesOf(nodes: WorkflowNode[], ids: Iterable<string>): string;
197
+ /**
198
+ * One edit to a node, described by which of its fields moved.
199
+ *
200
+ * The run key carries the CHANGED FIELDS, not just the node, and that is the
201
+ * difference between a useful granularity and an irritating one: typing into a
202
+ * name box folds into one action, but typing a name and then flipping a switch
203
+ * on the same node a moment later stays two — because the second edit touches a
204
+ * different field and so opens a new run. Without the field in the key those two
205
+ * would merge, and undoing the switch would silently retype the name.
206
+ *
207
+ * The fields are read through `Object.entries` rather than by name: a node is a
208
+ * union of six shapes with different fields each, and a hand-written list here
209
+ * would go quietly out of date the next time a node kind gains one — which
210
+ * shows up as an edit that mysteriously will not undo on its own.
211
+ */
212
+ export declare function nodeEditAction(before: WorkflowNode | undefined, after: WorkflowNode): EditAction;
213
+ /** What Reset is about to do, in the numbers the person can check it against. */
214
+ export declare function resetDescription(draft: HistoricDraft): string;
215
+ /**
216
+ * A tab that will not close on unsaved work without asking.
217
+ *
218
+ * Registered only while there IS unsaved work, which is the whole design
219
+ * constraint: a page that always warns teaches people to dismiss the dialog
220
+ * without reading it, and then it is not a guard, it is a habit. Cleaning up on
221
+ * `dirty` going false is what makes a save silence it immediately.
222
+ *
223
+ * The wording belongs to the browser — every engine ignores whatever string a
224
+ * page supplies here, and has for a decade — so this asks for the dialog and
225
+ * says nothing. `returnValue` is set as well as `preventDefault` because Chrome
226
+ * and Safari have historically disagreed about which one arms it.
227
+ *
228
+ * Nothing happens on a server: `useEffect` does not run there, so a host
229
+ * rendering this canvas into HTML sees no `window`.
230
+ */
231
+ export declare function useUnsavedGuard(dirty: boolean): void;
232
+ /**
233
+ * Whether a key press belongs to something being typed into.
234
+ *
235
+ * The reason Cmd/Ctrl+Z can be bound at all. This canvas contains a name field,
236
+ * a description box, several config fields and a real code editor, and in every
237
+ * one of them Cmd+Z means "undo my typing" — a canvas-level binding that fired
238
+ * there would silently discard a graph edit instead, which is the worst possible
239
+ * outcome for a control whose entire job is not losing work.
240
+ *
241
+ * `closest` rather than the target itself: a contenteditable code surface puts
242
+ * the caret on a descendant span, so the event target is not the editable host.
243
+ * The dialog and sheet cases are the same argument one level up — a modal over
244
+ * the canvas is a different document with its own undo, and the canvas has no
245
+ * business acting on keys pressed inside it.
246
+ *
247
+ * Narrowed with `instanceof` rather than asserted: `event.target` is typed
248
+ * `EventTarget | null` and genuinely can be a `Window` or a text node.
249
+ */
250
+ export declare function isTypingTarget(target: EventTarget | null): boolean;
251
+ /**
252
+ * Cmd/Ctrl+Z, on the canvas and nowhere else.
253
+ *
254
+ * Shift+Cmd/Ctrl+Z is caught deliberately rather than left to the browser: the
255
+ * hands that reach for it are expecting a redo, and silence would read as a
256
+ * broken shortcut. It says there is none, once, in the same live region
257
+ * everything else on this canvas speaks through.
258
+ *
259
+ * On `window` rather than on the canvas element because the canvas is not
260
+ * reliably focused — somebody who has just clicked a toolbar button, or closed
261
+ * the inspector, has focus on chrome — and a shortcut that only works when the
262
+ * right thing happens to be focused is a shortcut people stop trusting.
263
+ */
264
+ export declare function useUndoShortcut({ enabled, onUndo, onSay, }: {
265
+ enabled: boolean;
266
+ onUndo: () => void;
267
+ onSay: (message: string) => void;
268
+ }): void;
269
+ /**
270
+ * Undo, Reset, and the fact that there is unsaved work — as one cluster.
271
+ *
272
+ * Together because they are one subject and answer each other: the chip says
273
+ * something is at risk, Undo takes back the last thing, Reset gives up on all of
274
+ * it. Split across the screen they would be three unrelated controls, and the
275
+ * chip in particular means nothing without something to do about it.
276
+ *
277
+ * The unsaved chip is `role="status"`, so it is announced when it appears rather
278
+ * than only when somebody goes looking. It appears once per clean→dirty
279
+ * transition, because its text does not change while dirty — a status that
280
+ * re-announced on every keystroke would be unusable.
281
+ */
282
+ export declare function HistoryControls({ draft, canEdit, reducedMotion, resetting, onResettingChange, onUndo, onReset, }: {
283
+ draft: HistoricDraft;
284
+ canEdit: boolean;
285
+ /** No pulse for somebody who has asked their machine to stop moving things. */
286
+ reducedMotion: boolean;
287
+ resetting: boolean;
288
+ onResettingChange: (open: boolean) => void;
289
+ onUndo: () => void;
290
+ onReset: () => void;
291
+ }): import("react/jsx-runtime").JSX.Element;