@dudousxd/nestjs-catalog-react 0.20.0 → 0.22.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, 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';
1
+ import type { CallableWorkflowRef, CatalogAuditEvent, CatalogConnection, CatalogConnector, CatalogObjectPage, CatalogQueryRelation, CatalogQueryResult, CatalogReusableNode, CatalogRevision, CatalogSearchResult, CatalogSnapshot, CatalogTrace, CatalogTraceList, CatalogTransform, ConnectionCheck, ConnectorRun, Dashboard, DashboardCard, DeleteReconciliation, LoadExpectation, LoadExpectationInput, ObjectQueryParams, PropertyPatch, ResolvedLoadExpectation, ReusableNodeBody, 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';
@@ -168,6 +168,69 @@ export interface ConnectionUse {
168
168
  status: CatalogWorkflow['status'];
169
169
  through: string;
170
170
  }
171
+ /**
172
+ * One place a shared node body — or a transform — is used.
173
+ *
174
+ * The same shape for both, because they answer the same question about two
175
+ * stored objects and a second shape would be a second thing to keep in step.
176
+ * `CatalogReusableNodeUse` in core is the server's word for it; this is the same
177
+ * fields, re-declared here rather than imported for the reason
178
+ * {@link ConnectionUse} is: the transform route answers this shape too, and core
179
+ * has no type that covers both.
180
+ *
181
+ * Per **node**, not per graph. Three nodes of one graph using the same body are
182
+ * three places an edit lands, which is what somebody about to edit it is asking.
183
+ */
184
+ export interface ReusableNodeUsage {
185
+ workflowId: string;
186
+ workflowName: string;
187
+ status: CatalogWorkflow['status'];
188
+ nodeId: string;
189
+ nodeName: string;
190
+ /**
191
+ * The version this node pinned, or absent for a reference that follows the
192
+ * latest.
193
+ *
194
+ * The field that turns a count into a decision. An unpinned node picks up this
195
+ * edit on its next run; a pinned one does not, until somebody edits that
196
+ * graph. A usage list without it would say "four graphs" and leave the reader
197
+ * unable to tell how many of them they are about to change.
198
+ */
199
+ pinnedVersion?: number;
200
+ }
201
+ /**
202
+ * A reusable node as the picker sees it: the body, plus how many places use it.
203
+ *
204
+ * The count is on the row rather than behind a request per row, because there is
205
+ * no library screen — the maintainer was explicit that reusable nodes belong
206
+ * where a node is added — so this list IS the picker, and a number that changes
207
+ * somebody's decision has to be there before the click.
208
+ */
209
+ export interface ListedReusableNode extends CatalogReusableNode {
210
+ usedBy: number;
211
+ }
212
+ export interface ReusableNodeInput {
213
+ id?: string;
214
+ name: string;
215
+ description?: string;
216
+ body: ReusableNodeBody;
217
+ }
218
+ /**
219
+ * What lifting a node into the library answers with.
220
+ *
221
+ * `setOnNode` rather than an edited graph, and it is the server saying out loud
222
+ * what the caller still has to do: the node is not an instance of anything until
223
+ * `useId` is on it and the graph is saved. A call that had rewritten the graph
224
+ * itself would move its version for a reason its author cannot see in their own
225
+ * diff, which is the class of silence this whole feature exists to end.
226
+ */
227
+ export interface SavedNodeAsReusable {
228
+ reusableNode: CatalogReusableNode;
229
+ setOnNode: {
230
+ nodeId: string;
231
+ useId: string;
232
+ };
233
+ }
171
234
  /**
172
235
  * What a manual run may say about itself.
173
236
  *
@@ -606,6 +669,20 @@ export interface CatalogClient {
606
669
  * thing the screen has to be able to say out loud.
607
670
  */
608
671
  listTransformRevisions(id: string): Promise<CatalogRevision[]>;
672
+ /**
673
+ * Which graphs run this transform, and at which node within each.
674
+ *
675
+ * The answer to "how many places use this", asked of the shared object that
676
+ * already existed. Read in the transform editor rather than in a listing,
677
+ * because the number changes a decision exactly when somebody is about to edit
678
+ * code four other graphs depend on — which is not a moment they spend on a
679
+ * listing page.
680
+ *
681
+ * `pinnedVersion` is what turns the count into a decision rather than an
682
+ * alarm: an unpinned node moves the moment this is saved, a pinned one does
683
+ * not, and the two need different amounts of care.
684
+ */
685
+ listTransformWorkflows(id: string): Promise<ReusableNodeUsage[]>;
609
686
  /**
610
687
  * Run code against sample records without storing anything.
611
688
  *
@@ -627,6 +704,40 @@ export interface CatalogClient {
627
704
  * rather than as a toast a minute later. Sharing the code is not the same as
628
705
  * trusting the client: this call is still made, and its refusal always wins.
629
706
  */
707
+ /**
708
+ * Node bodies saved under a name and used from several graphs, each with the
709
+ * number of places it is used.
710
+ *
711
+ * There is deliberately no library screen behind this. It is the source of the
712
+ * picker offered where a node is added, and the count rides along on every row
713
+ * rather than behind a request per row — a number that changes somebody's
714
+ * decision has to be there before the click.
715
+ *
716
+ * Refuses by name on a deployment whose store cannot hold reusable nodes,
717
+ * rather than answering an empty list. "There are none yet" and "there cannot
718
+ * be any here" look identical to somebody who has never seen one, and the
719
+ * first invites them to keep looking for the button.
720
+ */
721
+ listReusableNodes(): Promise<ListedReusableNode[]>;
722
+ saveReusableNode(input: ReusableNodeInput): Promise<CatalogReusableNode>;
723
+ deleteReusableNode(id: string): Promise<{
724
+ deleted: boolean;
725
+ }>;
726
+ /** Which graphs use it, and at which node within each. */
727
+ listReusableNodeWorkflows(id: string): Promise<ReusableNodeUsage[]>;
728
+ /**
729
+ * Lift one node of a saved graph into a reusable node, by reference.
730
+ *
731
+ * **It does not edit the graph.** It answers with the reusable node and the
732
+ * `useId` to put on that node; setting it and saving is one ordinary
733
+ * {@link CatalogClient.saveWorkflow}, which bumps the graph's version and
734
+ * shows a diff. A call that stored one thing and silently rewrote another
735
+ * would move a version for a reason its author cannot see in their own diff.
736
+ */
737
+ saveNodeAsReusable(workflowId: string, nodeId: string, input: {
738
+ name?: string;
739
+ description?: string;
740
+ }): Promise<SavedNodeAsReusable>;
630
741
  listWorkflows(): Promise<CatalogWorkflow[]>;
631
742
  saveWorkflow(input: WorkflowInput): Promise<CatalogWorkflow>;
632
743
  /**
@@ -807,6 +918,17 @@ export declare const catalogQueryKeys: {
807
918
  * today's code, which is the one thing it exists not to do.
808
919
  */
809
920
  transformRevisions: (id: string) => readonly ["nestjs-catalog", "pipeline", "transforms", string, "revisions"];
921
+ /**
922
+ * Which graphs run one transform, keyed UNDER `transforms` for the reason its
923
+ * neighbour above is: saving a graph is what changes this, and the list
924
+ * invalidation a save already performs has to reach it — a usage count that
925
+ * kept yesterday's number is worse than none, because it is read by somebody
926
+ * deciding whether an edit is safe.
927
+ */
928
+ transformWorkflows: (id: string) => readonly ["nestjs-catalog", "pipeline", "transforms", string, "workflows"];
929
+ reusableNodes: readonly ["nestjs-catalog", "pipeline", "reusable-nodes"];
930
+ /** Keyed under `reusableNodes`, so saving one invalidates its usage list too. */
931
+ reusableNodeWorkflows: (id: string) => readonly ["nestjs-catalog", "pipeline", "reusable-nodes", string, "workflows"];
810
932
  runs: (connectorId?: string) => readonly ["nestjs-catalog", "pipeline", "runs", string];
811
933
  /**
812
934
  * One type's resolved load expectation.
package/dist/context.js CHANGED
@@ -88,7 +88,13 @@ export function CatalogProvider({ transport, pipelineBasePath = DEFAULT_PIPELINE
88
88
  saveTransform: (input) => transport.post(pipeline.transforms(), input),
89
89
  deleteTransform: (id) => transport.delete(pipeline.transform(id)),
90
90
  listTransformRevisions: (id) => transport.get(pipeline.transformRevisions(id)),
91
+ listTransformWorkflows: (id) => transport.get(pipeline.transformWorkflows(id)),
91
92
  tryTransform: (input) => transport.post(pipeline.tryTransform(), input),
93
+ listReusableNodes: () => transport.get(pipeline.reusableNodes()),
94
+ saveReusableNode: (input) => transport.post(pipeline.reusableNodes(), input),
95
+ deleteReusableNode: (id) => transport.delete(pipeline.reusableNode(id)),
96
+ listReusableNodeWorkflows: (id) => transport.get(pipeline.reusableNodeWorkflows(id)),
97
+ saveNodeAsReusable: (workflowId, nodeId, input) => transport.post(pipeline.saveNodeAsReusable(workflowId, nodeId), input),
92
98
  listWorkflows: () => transport.get(pipeline.workflows()),
93
99
  saveWorkflow: (input) => transport.post(pipeline.workflows(), input),
94
100
  publishWorkflow: (id) => transport.post(pipeline.publishWorkflow(id), {}),
@@ -192,6 +198,17 @@ export const catalogQueryKeys = {
192
198
  * today's code, which is the one thing it exists not to do.
193
199
  */
194
200
  transformRevisions: (id) => ['nestjs-catalog', 'pipeline', 'transforms', id, 'revisions'],
201
+ /**
202
+ * Which graphs run one transform, keyed UNDER `transforms` for the reason its
203
+ * neighbour above is: saving a graph is what changes this, and the list
204
+ * invalidation a save already performs has to reach it — a usage count that
205
+ * kept yesterday's number is worse than none, because it is read by somebody
206
+ * deciding whether an edit is safe.
207
+ */
208
+ transformWorkflows: (id) => ['nestjs-catalog', 'pipeline', 'transforms', id, 'workflows'],
209
+ reusableNodes: ['nestjs-catalog', 'pipeline', 'reusable-nodes'],
210
+ /** Keyed under `reusableNodes`, so saving one invalidates its usage list too. */
211
+ reusableNodeWorkflows: (id) => ['nestjs-catalog', 'pipeline', 'reusable-nodes', id, 'workflows'],
195
212
  runs: (connectorId) => ['nestjs-catalog', 'pipeline', 'runs', connectorId ?? 'all'],
196
213
  /**
197
214
  * One type's resolved load expectation.
package/dist/index.d.ts CHANGED
@@ -29,7 +29,7 @@ export { WORKFLOW_NAME } from './workflow/name';
29
29
  export { checkShapes, type ShapeKnowledge, type SourceColumn, type SourceShape, type TargetProperty, type TargetShape, } from './workflow/shape';
30
30
  export { canConnect, type ConnectionVerdict, edgeId, hasBlockingProblem, problemsByNode, type ValidateOptions, validateWorkflow, type WorkflowDraft, type WorkflowProblem, type WorkflowProblemCode, type WorkflowProblemLevel, wouldCycle, } from './workflow/validate';
31
31
  export { attachTransformIds, buildWorkflowTemplate, type EnrichOptions, enrichWithLookup, fanOutTypes, type FanOutOptions, type FanOutTarget, FILE_DROP_KINDS, type FileDropOptions, joinSources, type JoinOptions, loadFileDrop, type PeriodicFullReloadOptions, periodicFullReload, planIsRunnable, planToWorkflowInput, refuseUnusableColumnNames, RELOAD_CADENCE_IDS, RELOAD_CADENCES, type ReloadCadence, replicateTable, type ReplicateTableOptions, SOURCE_KINDS, type TemplateDeclaration, type TemplateExpectation, type TemplateOutcome, type TemplatePlan, type TemplateRefusal, type TemplateRefusalCode, type TemplateRequest, type TemplateSchedule, type TemplateTransformRequest, withinMsFor, WORKFLOW_TEMPLATE_IDS, WORKFLOW_TEMPLATES, type WorkflowTemplateId, type WorkflowTemplateMeta, } from './workflow/templates';
32
- export { type CatalogClient, type CatalogIdentity, type CatalogRevision, type CatalogPeoplePage, type CatalogPersonRole, type CatalogPersonSummary, type CatalogPrincipalSummary, CatalogProvider, type CatalogProviderProps, type CatalogTransport, type ConnectionInput, type ConnectionUse, catalogQueryKeys, type DeleteReconciliation, type LoadExpectation, type LoadExpectationInput, type ResolvedLoadExpectation, type RowCountBound, type StoredLoadExpectation, type PersonInput, type PersonUpsertResult, type PipelineCapabilities, type CallableWorkflowList, type ScheduledWorkflow, type TransformInput, type WorkflowRunOptions, type WorkflowScheduleInput, useCatalogClient, } from './context';
32
+ export { type CatalogClient, type CatalogIdentity, type CatalogRevision, type CatalogPeoplePage, type CatalogPersonRole, type CatalogPersonSummary, type CatalogPrincipalSummary, CatalogProvider, type CatalogProviderProps, type CatalogTransport, type ConnectionInput, type ConnectionUse, catalogQueryKeys, type DeleteReconciliation, type LoadExpectation, type LoadExpectationInput, type ResolvedLoadExpectation, type RowCountBound, type StoredLoadExpectation, type PersonInput, type PersonUpsertResult, type PipelineCapabilities, type CallableWorkflowList, type ScheduledWorkflow, type TransformInput, type ListedReusableNode, type ReusableNodeInput, type ReusableNodeUsage, type SavedNodeAsReusable, type WorkflowRunOptions, type WorkflowScheduleInput, useCatalogClient, } from './context';
33
33
  export { type AccessRoutes, accessRoutes, DEFAULT_ACCESS_BASE_PATH, DEFAULT_PIPELINE_BASE_PATH, DEFAULT_PUBLISH_BASE_PATH, embedRoutes, type PeopleQuery, type PipelineRoutes, pipelineRoutes, } from './routes';
34
34
  export { ConfirmDialog } from './ui/dialog';
35
35
  export { FieldGroup, TextAreaField, TextField } from './ui/field';
package/dist/routes.d.ts CHANGED
@@ -170,7 +170,43 @@ export interface PipelineRoutes {
170
170
  * traceable and the code did not.
171
171
  */
172
172
  transformRevisions(id: string): string;
173
+ /**
174
+ * Which graphs run this transform, and at which node within each.
175
+ *
176
+ * The sibling of {@link PipelineRoutes.connectionWorkflows}, one shared object
177
+ * over. Both are pressed by somebody about to change something and wondering
178
+ * who is downstream, and both are answerable only because the reference is by
179
+ * id rather than by copy.
180
+ *
181
+ * A sub-resource rather than a count on `transforms`, unlike
182
+ * {@link PipelineRoutes.reusableNodes} which does carry one. The difference is
183
+ * where the number is read: a reusable node's count is rendered on the row of
184
+ * a picker somebody is about to click, and a transform's is read once, in an
185
+ * editor already open on one transform.
186
+ */
187
+ transformWorkflows(id: string): string;
173
188
  tryTransform(): string;
189
+ /**
190
+ * Node bodies saved under a name and used from several graphs. GET lists
191
+ * (each with a `usedBy` count), POST creates or updates one.
192
+ *
193
+ * There is deliberately **no library screen** behind this, and no tab. The
194
+ * maintainer was explicit that reusable nodes belong where a node is added
195
+ * rather than in a listing of their own, so this list is the picker's source:
196
+ * the count rides along on every row, because a number that changes somebody's
197
+ * decision has to be there before the click rather than one request after it.
198
+ */
199
+ reusableNodes(): string;
200
+ reusableNode(id: string): string;
201
+ /**
202
+ * Which graphs use this reusable node, and at which node within each.
203
+ *
204
+ * Reports each *node*, not each graph — three nodes in one graph are three
205
+ * places an edit lands, which is the question somebody about to edit a shared
206
+ * body is actually asking. {@link PipelineRoutes.connectionWorkflows} reports
207
+ * each graph once, because deleting a connection breaks a graph once.
208
+ */
209
+ reusableNodeWorkflows(id: string): string;
174
210
  /**
175
211
  * Authored graphs of transforms. GET lists, POST creates or updates.
176
212
  *
@@ -218,6 +254,18 @@ export interface PipelineRoutes {
218
254
  * a source has a shape to report.
219
255
  */
220
256
  discoverSourceSchema(id: string, nodeId: string): string;
257
+ /**
258
+ * Lift one node of a graph into a reusable node, by reference.
259
+ *
260
+ * Beside `.../discover` because it is the same shape of thing: an action on
261
+ * one node of one graph. It stores the body and answers with the reusable
262
+ * node and the `useId` to put on that node — **it does not edit the graph**,
263
+ * because a route that stored one thing and silently rewrote another would
264
+ * move a graph's version for a reason its author cannot see in their own diff.
265
+ * The caller sets `useId` and saves the graph, which is one ordinary
266
+ * {@link PipelineRoutes.workflows} POST.
267
+ */
268
+ saveNodeAsReusable(id: string, nodeId: string): string;
221
269
  /**
222
270
  * Every per-type load expectation an operator has stored.
223
271
  *
package/dist/routes.js CHANGED
@@ -143,7 +143,11 @@ export function pipelineRoutes(basePath = DEFAULT_PIPELINE_BASE_PATH) {
143
143
  transforms: () => `${base}/transforms`,
144
144
  transform: (id) => `${base}/transforms/${encodeURIComponent(id)}`,
145
145
  transformRevisions: (id) => `${base}/transforms/${encodeURIComponent(id)}/revisions`,
146
+ transformWorkflows: (id) => `${base}/transforms/${encodeURIComponent(id)}/workflows`,
146
147
  tryTransform: () => `${base}/transforms/try`,
148
+ reusableNodes: () => `${base}/reusable-nodes`,
149
+ reusableNode: (id) => `${base}/reusable-nodes/${encodeURIComponent(id)}`,
150
+ reusableNodeWorkflows: (id) => `${base}/reusable-nodes/${encodeURIComponent(id)}/workflows`,
147
151
  workflows: () => `${base}/workflows`,
148
152
  workflow: (id) => `${base}/workflows/${encodeURIComponent(id)}`,
149
153
  publishWorkflow: (id) => `${base}/workflows/${encodeURIComponent(id)}/publish`,
@@ -151,6 +155,7 @@ export function pipelineRoutes(basePath = DEFAULT_PIPELINE_BASE_PATH) {
151
155
  runWorkflow: (id) => `${base}/workflows/${encodeURIComponent(id)}/run`,
152
156
  workflowSchedule: (id) => `${base}/workflows/${encodeURIComponent(id)}/schedule`,
153
157
  discoverSourceSchema: (id, nodeId) => `${base}/workflows/${encodeURIComponent(id)}/nodes/${encodeURIComponent(nodeId)}/discover`,
158
+ saveNodeAsReusable: (id, nodeId) => `${base}/workflows/${encodeURIComponent(id)}/nodes/${encodeURIComponent(nodeId)}/save-as-reusable`,
154
159
  loadExpectations: () => expectations.expectations(),
155
160
  loadExpectation: (typeName) => expectations.expectation(typeName),
156
161
  };
@@ -0,0 +1,161 @@
1
+ import { type WorkflowBranchLabel, type WorkflowEdge, type WorkflowNode, type WorkflowNodeKind } from './model';
2
+ /**
3
+ * What right-clicking something on this canvas offers, worked out from the graph.
4
+ *
5
+ * ## The problem this is really solving
6
+ *
7
+ * "Create the next node and wire it in one action" already existed. It lives in
8
+ * a pill on a node's hover toolbar, roughly 46×20 pixels on a 1600-pixel canvas,
9
+ * and the person who asked for this feature never found it. When told it was
10
+ * there they answered: *"Apertei na borda e só deu wire ué"* — they pressed the
11
+ * handle, got the click-to-connect gesture, and reasonably concluded that was
12
+ * the feature. **Two different affordances were both called "wire", and the one
13
+ * carrying the menu was the less visible of the two.**
14
+ *
15
+ * So a context menu here is not a convenience on top of a discovered feature. It
16
+ * is the discoverable home for a capability that already shipped and was being
17
+ * missed, and everything else follows from that: the same list is what the hover
18
+ * pill opens (renamed, because the collision of names was half the bug), so
19
+ * there is one set of node actions in this package and no way for two menus to
20
+ * drift apart.
21
+ *
22
+ * ## The two rules everything here obeys
23
+ *
24
+ * **Never offer something the graph would refuse.** Every option that makes an
25
+ * edge is filtered through `canConnect` — the same function the drag, the click
26
+ * gesture and the inspector's picker are all refused by — by building a
27
+ * throwaway node and asking. Nothing here restates a rule about what may follow
28
+ * what. And where a list comes out empty, the menu *says why* instead of showing
29
+ * a blank space: "nothing here" and "nothing is possible" look identical and
30
+ * mean completely different things, and for a sink the answer is permanent.
31
+ *
32
+ * **Destructive items are separated.** `separated` puts a rule and a gap above a
33
+ * section, and delete is always the last section on the menu, on its own, in the
34
+ * destructive tone. It is still true that a variable-length "Already wired"
35
+ * group above it moves it between openings; what is avoided is the worse case —
36
+ * an ordinary item and a destructive one trading places at the same coordinates.
37
+ *
38
+ * ## Why this is a model and not JSX
39
+ *
40
+ * Two surfaces render it, and a third could. Keeping it as data means the
41
+ * question a reviewer actually cares about — *does a sink get offered anything
42
+ * downstream, ever?* — is a plain assertion over an array rather than a DOM
43
+ * query against a portalled popup that jsdom cannot lay out.
44
+ */
45
+ /** What was right-clicked. The four things this canvas can distinguish. */
46
+ export type CanvasMenuTarget = {
47
+ kind: 'node';
48
+ nodeId: string;
49
+ } | {
50
+ kind: 'edge';
51
+ edge: WorkflowEdge;
52
+ }
53
+ /** Empty canvas, with the point in GRAPH coordinates — where a node would land. */
54
+ | {
55
+ kind: 'pane';
56
+ at: {
57
+ x: number;
58
+ y: number;
59
+ };
60
+ }
61
+ /** Several nodes at once. Only ever reached with two or more. */
62
+ | {
63
+ kind: 'selection';
64
+ nodeIds: string[];
65
+ };
66
+ /**
67
+ * The mark beside an item.
68
+ *
69
+ * A name rather than an element, so this module stays data and the icon set
70
+ * stays an implementation detail of whichever surface draws it.
71
+ */
72
+ export type CanvasMenuIcon = 'open' | 'code' | 'arrow' | 'plus' | 'insert' | 'branch' | 'unplug' | 'trash' | 'tidy' | 'fit';
73
+ export interface CanvasMenuItem {
74
+ key: string;
75
+ label: string;
76
+ /** The right-hand column: what this does, in two or three words. */
77
+ hint?: string;
78
+ icon: CanvasMenuIcon;
79
+ /** Set on anything that removes something. Colours it, and nothing else. */
80
+ destructive?: boolean;
81
+ /**
82
+ * A sentence under the label, for the one case where the cost is not obvious
83
+ * from it. Used for exactly two things today — the wires a node takes with it,
84
+ * and what removing a node from a PUBLISHED graph does — because a warning on
85
+ * every item is a warning nobody reads.
86
+ */
87
+ detail?: string;
88
+ run(): void;
89
+ }
90
+ export interface CanvasMenuSection {
91
+ key: string;
92
+ title?: string;
93
+ /**
94
+ * Rendered instead of an empty list.
95
+ *
96
+ * The whole reason a section can be empty and still present: a sink offered no
97
+ * downstream targets has to say "a sink commits its rows, nothing runs after
98
+ * one" rather than show a gap that reads like a loading state.
99
+ */
100
+ note?: string;
101
+ /** A rule and a gap above it. Every destructive section sets this. */
102
+ separated?: boolean;
103
+ items: CanvasMenuItem[];
104
+ }
105
+ /**
106
+ * Everything the menu can ask the canvas to do.
107
+ *
108
+ * Handed in rather than dispatched through a union the canvas then switches on,
109
+ * because every one of these already exists on the canvas as a named callback
110
+ * with its own announcement and its own `markStarted` bookkeeping. A second
111
+ * dispatch layer would be a place for one of them to be forgotten.
112
+ */
113
+ export interface CanvasMenuActions {
114
+ inspect(nodeId: string): void;
115
+ editCode(nodeId: string): void;
116
+ connect(from: string, to: string): void;
117
+ connectToNew(from: string, kind: WorkflowNodeKind): void;
118
+ insertBetween(edge: WorkflowEdge, kind: WorkflowNodeKind): void;
119
+ setBranch(edge: WorkflowEdge, branch: WorkflowBranchLabel): void;
120
+ disconnect(edge: WorkflowEdge): void;
121
+ removeNodes(ids: string[]): void;
122
+ addAt(kind: WorkflowNodeKind, at: {
123
+ x: number;
124
+ y: number;
125
+ }): void;
126
+ tidy(): void;
127
+ fitAll(): void;
128
+ fitNodes(ids: string[]): void;
129
+ }
130
+ export interface CanvasMenuContext {
131
+ nodes: WorkflowNode[];
132
+ edges: WorkflowEdge[];
133
+ /** Every kind that can exist, in the order the palette offers them. */
134
+ kinds: readonly WorkflowNodeKind[];
135
+ canEdit: boolean;
136
+ /**
137
+ * Whether the STORED graph is published.
138
+ *
139
+ * Changes one sentence and no behaviour. A published graph has to stay
140
+ * runnable — the server refuses a save that would leave one unable to run, in
141
+ * those words — so removing a node from one is an edit that will be turned
142
+ * away at the moment it is saved rather than at the moment it is made. Saying
143
+ * so on the item is the difference between finding that out now and finding it
144
+ * out after twenty minutes of further editing.
145
+ */
146
+ published: boolean;
147
+ actions: CanvasMenuActions;
148
+ }
149
+ export declare function buildCanvasMenu(target: CanvasMenuTarget, context: CanvasMenuContext): CanvasMenuSection[];
150
+ /**
151
+ * What removing this node costs, in one sentence, or nothing at all.
152
+ *
153
+ * Two facts, and only when they apply. The wires, because a node removal that
154
+ * quietly unwires two OTHER nodes and says nothing is how somebody finds out
155
+ * half an hour later that their graph no longer reaches its sink. And the
156
+ * published case, because the server enforces a rule this canvas cannot: a
157
+ * published graph has to stay runnable, so the edit is accepted here and refused
158
+ * at the save — the one place a warning in advance is worth more than a
159
+ * confirmation dialog.
160
+ */
161
+ export declare function deleteCost(wires: number, published: boolean): string | undefined;