@flowdrop/flowdrop 2.3.0 → 2.4.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 CHANGED
@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [2.4.0] - 2026-08-23
9
+
10
+ ### Added
11
+
12
+ - **A port's shape now comes from the server when the server declares one.** fddo 2.x serves a JSON Schema per lane (`PortDataTypeConfig.schema`, from its port-shape registry), and `portShape()` reads that schema's `type` ahead of the client's static lane table. The table stays as the fallback — it is what answers on an older fddo, on a third-party server implementing only the port-config endpoint, and on the library's offline defaults, which carry no schemas on purpose. A site's own shape now shapes its own lane: declare `Order` as `type: object` and its ports draw `{}` without this library having heard of it.
13
+
14
+ - **Template variables drill into the fields a port's lane declares.** A template author could reach an `error` port and nothing inside it. A port with no schema of its own now resolves one from its lane, so the four fields of an error payload are offered as `error.message`, `error.code`, `error.node_id` and `error.retryable` — declared once on the lane, restated nowhere. `NodePort.schema` stays empty and stays the per-port refinement slot: what wants it is the narrower schema a run observed for this port on this node, which is per-instance information and could never travel on a payload cached per node type.
15
+ - **This needs a backend that serves it.** fddo serves lane schemas on `2.x`; anything older serves none, and autocomplete then stops at the port exactly as it did before. One caveat worth knowing: a site with a stored `port_config` entry for a lane replaces the composed entry outright, `schema` included — so a site that once customised the `error` lane sees no field list until it re-adds one. That is the port-config overlay's existing whole-entry merge semantics, not a new rule.
16
+
17
+ ### Changed
18
+
19
+ - **`getVariableSchema()`'s trailing arguments became one context object.** It had grown to eight positionals, the last three optional and one of them a service, so a call site read `..., workflowId, authProvider, fd.portCompatibility)` and could not be read without counting commas. It is now `(endpointConfig, node, nodes, edges, config, {workflowId, authProvider, portCompatibility})`. **Not a public break** — `variableService` is not exported from any package entry point; the change is listed because its docblock's examples were wrong in the released source (they omitted the first argument entirely) and are now correct.
20
+
21
+ ### Deprecated
22
+
23
+ - **`portGlyph()`** — use `SHAPE_GLYPH[portShape(checker, port)]`, which is what it does. Both it and the map shipped in 2.3.0's public surface and only one of them needed to. It keeps working until 3.0.0.
24
+
25
+ ### Fixed
26
+
27
+ - **The reserved `error` port drew `?` on every node.** fddo declares the `error` lane as `type: object` and has since its shape registry shipped; the client's lane table has no `error` entry, so the shape fell through to `unknown` while the lane chip beside it was correctly coloured red and — after the change above — while autocomplete was offering the payload's four fields. It draws `{}` now. Same class of disagreement for any served lane the table does not name.
28
+
29
+ - **Six responsive utility classes had never matched anything.** `.flowdrop-sm\:flex`, `.flowdrop-md\:hidden` and their siblings escaped the colon twice, so the selectors were never valid; nothing in the library or the demo apps used them, and this repo lints no CSS, so nothing was ever going to say so. Removed rather than repaired — two display utilities across three breakpoints is not a responsive system, and a consumer needing one can write it against their own breakpoints.
30
+
8
31
  ## [2.3.0] - 2026-08-22
9
32
 
10
33
  ### Added
@@ -577,7 +577,10 @@
577
577
  // Compute the variable schema with optional port filtering and port name prefixing
578
578
  const computedSchema = getAvailableVariables(node, workflowNodes, workflowEdges, {
579
579
  targetPortIds: variablesConfig?.ports,
580
- includePortName: variablesConfig?.includePortName
580
+ includePortName: variablesConfig?.includePortName,
581
+ // Lets a variable drill into the fields its port's LANE declares —
582
+ // `error.message` rather than only `error`.
583
+ portCompatibility: fd.portCompatibility
581
584
  });
582
585
 
583
586
  // Merge computed schema with any pre-defined schema
@@ -149,8 +149,7 @@
149
149
  nodes,
150
150
  edges,
151
151
  variables,
152
- workflowId,
153
- authProvider
152
+ { workflowId, authProvider, portCompatibility: fd.portCompatibility }
154
153
  );
155
154
  } catch (error) {
156
155
  logger.error('Failed to load variable schema:', error);
@@ -20,7 +20,7 @@
20
20
  <script lang="ts">
21
21
  import type { PortCompatibilityChecker } from '../../utils/connections.js';
22
22
  import { getPortColorToken } from '../../utils/colors.js';
23
- import { portGlyph, portShapeLabel } from '../../utils/portShape.js';
23
+ import { portShape, SHAPE_GLYPH, SHAPE_LABEL } from '../../utils/portShape.js';
24
24
 
25
25
  interface Props {
26
26
  /** The instance's port-compatibility checker — the source of lane colour. */
@@ -38,8 +38,10 @@
38
38
 
39
39
  /** Lane colour, or the reserved error output's red. */
40
40
  const color = $derived(getPortColorToken(checker, port));
41
- const glyph = $derived(portGlyph(checker, port));
42
- const label = $derived(portShapeLabel(checker, port));
41
+ /** Resolved once — the glyph and its tooltip are two readings of one shape. */
42
+ const shape = $derived(portShape(checker, port));
43
+ const glyph = $derived(SHAPE_GLYPH[shape]);
44
+ const label = $derived(SHAPE_LABEL[shape]);
43
45
  </script>
44
46
 
45
47
  <span
@@ -130,14 +130,17 @@ export { isLoopbackEdge, isValidLoopbackCycle, PortCompatibilityChecker, getPoss
130
130
  // A port's JSON-Schema shape and its semantic lane are two separate marks on
131
131
  // the canvas: a small coloured glyph for the shape, a quiet outlined chip for
132
132
  // the lane's name. `PortTypeBadge` draws one port's whole label row; the rest
133
- // is for a custom node component that wants the same glyph vocabulary. Both
134
- // functions take the instance's port-compatibility checker, the same source
133
+ // is for a custom node component that wants the same glyph vocabulary.
134
+ // `portShape` takes the instance's port-compatibility checker, the same source
135
135
  // colour reads, so a served or aliased lane shapes the way it colours. See
136
136
  // utils/portShape.ts for where the shape comes from.
137
137
  //
138
138
  // Deliberately small: the lane table, the shape labels and the two-component
139
139
  // split behind `PortTypeBadge` are implementation, and stay so until something
140
- // outside the library needs them.
140
+ // outside the library needs them. `portGlyph` is the one name here that fails
141
+ // that test — it is `SHAPE_GLYPH[portShape(…)]`, and shipping both it and the
142
+ // map was a surface we did not need. Deprecated rather than deleted: it went
143
+ // out in 2.3.0, so it leaves in 3.0.0.
141
144
  export { SHAPE_GLYPH, portShape, portGlyph } from '../utils/portShape.js';
142
145
  export { default as PortTypeBadge } from '../components/ports/PortTypeBadge.svelte';
143
146
  // ============================================================================
@@ -7,6 +7,7 @@
7
7
  */
8
8
  import type { WorkflowNode, WorkflowEdge, VariableSchema, TemplateVariable, TemplateVariablesConfig, AuthProvider } from '../types/index.js';
9
9
  import type { EndpointConfig } from '../config/endpoints.js';
10
+ import type { PortCompatibilityChecker } from '../utils/connections.js';
10
11
  /**
11
12
  * Options for deriving available variables.
12
13
  */
@@ -23,6 +24,15 @@ export interface GetAvailableVariablesOptions {
23
24
  * When false (default), schema properties are unpacked as top-level variables.
24
25
  */
25
26
  includePortName?: boolean;
27
+ /**
28
+ * The instance's port compatibility checker, used to read the schema a
29
+ * port's LANE declares when the port declares none of its own.
30
+ *
31
+ * Optional, and omitting it costs only depth: variables still resolve, they
32
+ * just stop at the port instead of drilling into its fields. That is the
33
+ * pre-shape behaviour, so an embedder that never passes it sees no change.
34
+ */
35
+ portCompatibility?: PortCompatibilityChecker;
26
36
  }
27
37
  /**
28
38
  * Derives available template variables from connected upstream nodes.
@@ -108,35 +118,65 @@ export declare function hasChildren(schema: VariableSchema, path: string): boole
108
118
  * ```
109
119
  */
110
120
  export declare function mergeVariableSchemas(primary: VariableSchema, secondary: VariableSchema): VariableSchema;
121
+ /**
122
+ * The optional context {@link getVariableSchema} resolves variables against.
123
+ *
124
+ * A bag rather than three more positional parameters: the required five say
125
+ * WHAT to resolve, and everything here says what is available while doing it.
126
+ * The signature had grown to eight positionals, of which the last three were
127
+ * optional and one was a service — a call site read
128
+ * `..., workflowId, authProvider, fd.portCompatibility)` and there was no
129
+ * reading it without counting commas.
130
+ */
131
+ export interface GetVariableSchemaContext {
132
+ /** Workflow id, for the API mode's endpoint interpolation. */
133
+ workflowId?: string;
134
+ /** Auth provider for the API-mode request. */
135
+ authProvider?: AuthProvider;
136
+ /**
137
+ * The instance's port compatibility checker, used to read the schema a port's
138
+ * LANE declares when the port declares none of its own. Omitting it costs
139
+ * only depth — see {@link GetAvailableVariablesOptions.portCompatibility}.
140
+ */
141
+ portCompatibility?: PortCompatibilityChecker;
142
+ }
111
143
  /**
112
144
  * Gets variable schema using the appropriate mode (API, schema-based, or hybrid).
113
145
  * This is the main orchestration function that determines how to fetch variables
114
146
  * based on the configuration.
115
147
  *
148
+ * @param endpointConfig - API endpoint configuration, or null when there is none
116
149
  * @param node - The current node being configured
117
150
  * @param nodes - All nodes in the workflow
118
151
  * @param edges - All edges in the workflow
119
152
  * @param config - Template variables configuration
120
- * @param workflowId - Optional workflow ID for API context
121
- * @param authProvider - Optional auth provider for API requests
153
+ * @param context - Optional resolution context: workflow id, auth provider, and
154
+ * the port compatibility checker
122
155
  * @returns A promise that resolves to the variable schema
123
156
  *
124
157
  * @example
125
158
  * ```typescript
126
159
  * // Schema-based mode (existing behavior)
127
160
  * const config = { ports: ["data"], schema: {...} };
128
- * const schema = await getVariableSchema(node, nodes, edges, config);
161
+ * const schema = await getVariableSchema(null, node, nodes, edges, config);
129
162
  *
130
163
  * // API mode
131
164
  * const config = { api: { endpoint: { url: "/api/variables/{workflowId}/{nodeId}" } } };
132
- * const schema = await getVariableSchema(node, nodes, edges, config, workflowId, authProvider);
165
+ * const schema = await getVariableSchema(endpointConfig, node, nodes, edges, config, {
166
+ * workflowId,
167
+ * authProvider
168
+ * });
133
169
  *
134
- * // Hybrid mode (API + static schema)
170
+ * // Hybrid mode (API + static schema), drilling into each port's lane schema
135
171
  * const config = {
136
172
  * schema: {...},
137
173
  * api: { endpoint: {...}, mergeWithSchema: true }
138
174
  * };
139
- * const schema = await getVariableSchema(node, nodes, edges, config, workflowId, authProvider);
175
+ * const schema = await getVariableSchema(endpointConfig, node, nodes, edges, config, {
176
+ * workflowId,
177
+ * authProvider,
178
+ * portCompatibility: fd.portCompatibility
179
+ * });
140
180
  * ```
141
181
  */
142
- export declare function getVariableSchema(endpointConfig: EndpointConfig | null, node: WorkflowNode, nodes: WorkflowNode[], edges: WorkflowEdge[], config: TemplateVariablesConfig, workflowId?: string, authProvider?: AuthProvider): Promise<VariableSchema>;
182
+ export declare function getVariableSchema(endpointConfig: EndpointConfig | null, node: WorkflowNode, nodes: WorkflowNode[], edges: WorkflowEdge[], config: TemplateVariablesConfig, context?: GetVariableSchemaContext): Promise<VariableSchema>;
@@ -64,17 +64,42 @@ function propertyToTemplateVariable(name, property, sourcePort, sourceNode) {
64
64
  }
65
65
  return variable;
66
66
  }
67
+ /**
68
+ * The schema in force for a port: its own if it has one, else its lane's.
69
+ *
70
+ * A port's own schema is the refinement — narrower, and specific to this port —
71
+ * so it wins. The lane's schema is what a port shape declares, served once on
72
+ * the lane entry for every port that declares the lane, which is how the
73
+ * `error` port comes to know it carries `{message, code, node_id, retryable}`.
74
+ *
75
+ * Resolved through the checker rather than a private lookup, for the reason
76
+ * `portShape()` is: a table of its own cannot follow an alias, so the same
77
+ * lane could come back styled and schemaless at once.
78
+ *
79
+ * @param port - The port to resolve a schema for
80
+ * @param checker - The instance's compatibility checker, when one is available
81
+ * @returns The schema in force, or undefined when neither declares one
82
+ */
83
+ function resolvePortSchema(port, checker) {
84
+ if (port.schema)
85
+ return port.schema;
86
+ if (!checker || !port.dataType)
87
+ return undefined;
88
+ return checker.getDataTypeConfig(port.dataType)?.schema;
89
+ }
67
90
  /**
68
91
  * Creates a TemplateVariable from a NodePort.
69
- * Uses the port's schema if available, otherwise creates a basic variable.
92
+ * Uses the schema in force for the port if there is one, otherwise creates a
93
+ * basic variable from the port's lane.
70
94
  *
71
95
  * @param port - The output port to convert
72
96
  * @param sourceNode - The source node ID
97
+ * @param schema - The schema in force, from {@link resolvePortSchema}
73
98
  * @returns A TemplateVariable representing the port's data
74
99
  */
75
- function portToTemplateVariable(port, sourceNode) {
76
- // If the port has a schema, use it to build a detailed variable
77
- if (port.schema && port.schema.properties) {
100
+ function portToTemplateVariable(port, sourceNode, schema) {
101
+ // If a schema is in force, use it to build a detailed variable
102
+ if (schema && schema.properties) {
78
103
  const variable = {
79
104
  name: port.id,
80
105
  label: port.name,
@@ -84,7 +109,7 @@ function portToTemplateVariable(port, sourceNode) {
84
109
  sourceNode,
85
110
  properties: {}
86
111
  };
87
- for (const [propName, propValue] of Object.entries(port.schema.properties)) {
112
+ for (const [propName, propValue] of Object.entries(schema.properties)) {
88
113
  variable.properties[propName] = propertyToTemplateVariable(propName, propValue, port.id, sourceNode);
89
114
  }
90
115
  return variable;
@@ -181,7 +206,7 @@ function findUpstreamConnections(node, nodes, edges) {
181
206
  */
182
207
  export function getAvailableVariables(node, nodes, edges, options) {
183
208
  const variables = {};
184
- const { targetPortIds, includePortName } = options ?? {};
209
+ const { targetPortIds, includePortName, portCompatibility } = options ?? {};
185
210
  // Find all upstream connections
186
211
  const connections = findUpstreamConnections(node, nodes, edges);
187
212
  for (const connection of connections) {
@@ -200,11 +225,14 @@ export function getAvailableVariables(node, nodes, edges, options) {
200
225
  }
201
226
  if (!sourcePort)
202
227
  continue;
203
- // If the source port has a schema with top-level properties,
204
- // unpack them as top-level variables (unless includePortName is true)
205
- if (sourcePort.schema?.properties && !includePortName) {
228
+ // The schema in force for this port: its own, else the one its lane
229
+ // declares. Resolved once, because both branches below read it.
230
+ const sourceSchema = resolvePortSchema(sourcePort, portCompatibility);
231
+ // If the schema has top-level properties, unpack them as top-level
232
+ // variables (unless includePortName is true)
233
+ if (sourceSchema?.properties && !includePortName) {
206
234
  // Unpack schema properties as top-level variables
207
- for (const [propName, propValue] of Object.entries(sourcePort.schema.properties)) {
235
+ for (const [propName, propValue] of Object.entries(sourceSchema.properties)) {
208
236
  // Skip if we already have a variable with this name
209
237
  if (variables[propName])
210
238
  continue;
@@ -217,7 +245,7 @@ export function getAvailableVariables(node, nodes, edges, options) {
217
245
  // Skip if we already have a variable with this name
218
246
  if (variables[variableName])
219
247
  continue;
220
- const variable = portToTemplateVariable(sourcePort, sourceNode.id);
248
+ const variable = portToTemplateVariable(sourcePort, sourceNode.id, sourceSchema);
221
249
  variable.name = variableName;
222
250
  variable.label = targetPort?.name ?? sourcePort.name;
223
251
  variables[variableName] = variable;
@@ -379,33 +407,42 @@ export function mergeVariableSchemas(primary, secondary) {
379
407
  * This is the main orchestration function that determines how to fetch variables
380
408
  * based on the configuration.
381
409
  *
410
+ * @param endpointConfig - API endpoint configuration, or null when there is none
382
411
  * @param node - The current node being configured
383
412
  * @param nodes - All nodes in the workflow
384
413
  * @param edges - All edges in the workflow
385
414
  * @param config - Template variables configuration
386
- * @param workflowId - Optional workflow ID for API context
387
- * @param authProvider - Optional auth provider for API requests
415
+ * @param context - Optional resolution context: workflow id, auth provider, and
416
+ * the port compatibility checker
388
417
  * @returns A promise that resolves to the variable schema
389
418
  *
390
419
  * @example
391
420
  * ```typescript
392
421
  * // Schema-based mode (existing behavior)
393
422
  * const config = { ports: ["data"], schema: {...} };
394
- * const schema = await getVariableSchema(node, nodes, edges, config);
423
+ * const schema = await getVariableSchema(null, node, nodes, edges, config);
395
424
  *
396
425
  * // API mode
397
426
  * const config = { api: { endpoint: { url: "/api/variables/{workflowId}/{nodeId}" } } };
398
- * const schema = await getVariableSchema(node, nodes, edges, config, workflowId, authProvider);
427
+ * const schema = await getVariableSchema(endpointConfig, node, nodes, edges, config, {
428
+ * workflowId,
429
+ * authProvider
430
+ * });
399
431
  *
400
- * // Hybrid mode (API + static schema)
432
+ * // Hybrid mode (API + static schema), drilling into each port's lane schema
401
433
  * const config = {
402
434
  * schema: {...},
403
435
  * api: { endpoint: {...}, mergeWithSchema: true }
404
436
  * };
405
- * const schema = await getVariableSchema(node, nodes, edges, config, workflowId, authProvider);
437
+ * const schema = await getVariableSchema(endpointConfig, node, nodes, edges, config, {
438
+ * workflowId,
439
+ * authProvider,
440
+ * portCompatibility: fd.portCompatibility
441
+ * });
406
442
  * ```
407
443
  */
408
- export async function getVariableSchema(endpointConfig, node, nodes, edges, config, workflowId, authProvider) {
444
+ export async function getVariableSchema(endpointConfig, node, nodes, edges, config, context) {
445
+ const { workflowId, authProvider, portCompatibility } = context ?? {};
409
446
  let resultSchema = { variables: {} };
410
447
  // Try API mode first (if configured)
411
448
  if (config.api) {
@@ -423,7 +460,8 @@ export async function getVariableSchema(endpointConfig, node, nodes, edges, conf
423
460
  if (config.api.mergeWithPorts) {
424
461
  const portSchema = getAvailableVariables(node, nodes, edges, {
425
462
  targetPortIds: config.ports,
426
- includePortName: config.includePortName
463
+ includePortName: config.includePortName,
464
+ portCompatibility
427
465
  });
428
466
  resultSchema = mergeVariableSchemas(resultSchema, portSchema);
429
467
  }
@@ -451,7 +489,8 @@ export async function getVariableSchema(endpointConfig, node, nodes, edges, conf
451
489
  if (config.ports !== undefined || !config.api) {
452
490
  const portSchema = getAvailableVariables(node, nodes, edges, {
453
491
  targetPortIds: config.ports,
454
- includePortName: config.includePortName
492
+ includePortName: config.includePortName,
493
+ portCompatibility
455
494
  });
456
495
  resultSchema = portSchema;
457
496
  }
@@ -1026,37 +1026,6 @@ p {
1026
1026
  opacity: 0.6;
1027
1027
  }
1028
1028
 
1029
- /* Responsive utilities */
1030
- @media (min-width: 640px) {
1031
- .flowdrop-sm\\:flex {
1032
- display: flex;
1033
- }
1034
-
1035
- .flowdrop-sm\\:hidden {
1036
- display: none;
1037
- }
1038
- }
1039
-
1040
- @media (min-width: 768px) {
1041
- .flowdrop-md\\:flex {
1042
- display: flex;
1043
- }
1044
-
1045
- .flowdrop-md\\:hidden {
1046
- display: none;
1047
- }
1048
- }
1049
-
1050
- @media (min-width: 1024px) {
1051
- .flowdrop-lg\\:flex {
1052
- display: flex;
1053
- }
1054
-
1055
- .flowdrop-lg\\:hidden {
1056
- display: none;
1057
- }
1058
- }
1059
-
1060
1029
  /* Color system - Category colors */
1061
1030
  .flowdrop-color--primary {
1062
1031
  background-color: var(--fd-primary);
@@ -75,6 +75,38 @@ export interface PortDataTypeConfig {
75
75
  aliases?: string[];
76
76
  /** Whether this data type is enabled */
77
77
  enabled?: boolean;
78
+ /**
79
+ * The JSON Schema this lane promises, when a port shape declares one.
80
+ *
81
+ * This is what lets template autocomplete offer `error.message` rather than
82
+ * only `error`: the lane says what fields travel on it, once, for every port
83
+ * that declares the lane. Absent — not empty — when the lane promises
84
+ * nothing beyond its name, so "no promise" stays distinguishable from
85
+ * "an object with no properties".
86
+ *
87
+ * Authoring information only. Nothing validates a value against it, and a
88
+ * port may still carry a NARROWER {@link NodePort.schema} of its own, which
89
+ * wins.
90
+ */
91
+ schema?: PortSchema;
92
+ }
93
+ /**
94
+ * A JSON Schema as served on a lane entry or a port.
95
+ *
96
+ * Deliberately looser than {@link OutputSchema}: a lane may promise something
97
+ * that is not an object at all (the `messages` lane is a top-level `array`),
98
+ * and a JSON Schema's keyword space is not ours to enumerate — the backend
99
+ * stores it untyped for exactly that reason. Readers take `properties` when
100
+ * there is one and fall back to the port itself when there is not.
101
+ */
102
+ export interface PortSchema {
103
+ type?: string;
104
+ title?: string;
105
+ description?: string;
106
+ required?: string[];
107
+ properties?: Record<string, BaseProperty>;
108
+ items?: BaseProperty;
109
+ [key: string]: unknown;
78
110
  }
79
111
  /**
80
112
  * Port compatibility rule configuration
@@ -136,6 +168,13 @@ export interface NodePort {
136
168
  /**
137
169
  * Optional JSON Schema describing the structure of data on this port.
138
170
  * Used for template variable autocomplete to drill into nested properties.
171
+ *
172
+ * This is the per-port REFINEMENT slot, and it wins over the schema the
173
+ * port's lane declares ({@link PortDataTypeConfig.schema}), which is where a
174
+ * shape's own field list travels. It is left for the narrower thing: a
175
+ * schema that applies to this port on this node in this workflow rather than
176
+ * to the lane in general — a lane promising `object` whose values turn out
177
+ * to carry `{title, description}`. Nothing populates it yet.
139
178
  */
140
179
  schema?: OutputSchema | InputSchema;
141
180
  }
@@ -10,23 +10,33 @@
10
10
  *
11
11
  * ## Where the shape comes from
12
12
  *
13
- * The server's `NodePort` DTO carries no JSON Schema type today (`schema?` is
14
- * declared for template autocomplete and no producer populates it), so the
15
- * shape is derived client-side from the lane. Every lane FlowDrop ships implies
16
- * exactly one shape, so the map below answers the question against every
17
- * backend — including older fddo and third-party servers that only implement
18
- * the port-config endpoint.
13
+ * Two sources, in this order:
19
14
  *
20
- * Two things the derivation cannot do, both known and accepted:
15
+ * 1. **The lane's served schema** (`PortDataTypeConfig.schema`) — a JSON Schema
16
+ * the backend's shape registry declares for the lane. Its `type` IS the
17
+ * shape, said by the side that knows: fddo's `error` shape declares
18
+ * `type: object`, `messages` declares `type: array`, and a site's own
19
+ * `Order` shape answers for itself without the client having heard of it.
20
+ * 2. **The lane table below**, when no schema is served — which is every lane
21
+ * on an older fddo, on a third-party server implementing only the
22
+ * port-config endpoint, and on the library's offline defaults (which stay
23
+ * presentation-only on purpose and carry no schemas).
24
+ *
25
+ * The table was the whole answer before shapes reached the wire, and the
26
+ * ordering above is why the fallback stays: it is what draws a glyph when
27
+ * nothing declares one, not a second opinion competing with a served answer.
28
+ *
29
+ * Two things the fallback cannot do, both known and accepted:
21
30
  * - **`integer` vs `number` collapse.** The server already maps both onto lane
22
- * `number`, so nothing is lost that the client ever had.
23
- * - **A site-defined lane resolves to `unknown` (`?`).** A lane added through
24
- * the `port_config` overlay has no shape the client can know. `?` is the
25
- * honest answer.
31
+ * `number`, so nothing is lost that the client ever had. A served schema
32
+ * saying `integer` collapses the same way, for the same reason.
33
+ * - **A site-defined lane with no shape resolves to `unknown` (`?`).** A lane
34
+ * added through the `port_config` overlay alone has nothing to read. `?` is
35
+ * the honest answer, and declaring a shape for the lane is how a site
36
+ * improves it.
26
37
  *
27
- * {@link portShape} is the seam where that improves: a later release that
28
- * serves a shape per lane, or populates `NodePort.schema`, changes this one
29
- * function and no caller.
38
+ * {@link portShape} is the one function either source is read in, which is what
39
+ * kept adding the first source to a single place.
30
40
  *
31
41
  * It takes the **checker** for exactly that reason. Colour has always asked the
32
42
  * checker, which resolves an alias to its canonical lane and sees whatever the
@@ -83,19 +93,21 @@ interface ShapedPort {
83
93
  */
84
94
  export declare function laneShape(dataType: string | undefined): PortShape;
85
95
  /**
86
- * The shape to draw for a port — the seam described at the top of this file.
96
+ * The shape to draw for a port — both sources, in the order the top of this
97
+ * file states: the lane's served schema, then the table.
87
98
  *
88
- * Resolves the lane through the checker before consulting the table, so an
89
- * alias (`text` declared as an alias of `string`) is shaped as the lane it
90
- * aliases rather than as an unknown of its own.
99
+ * The lane is resolved through the checker either way, so an alias (`text`
100
+ * declared as an alias of `string`) reads the schema and the table of the lane
101
+ * it aliases rather than answering as an unknown of its own.
91
102
  */
92
103
  export declare function portShape(checker: PortCompatibilityChecker, port: ShapedPort): PortShape;
93
104
  /**
94
- * The glyph to draw for a port — the single entry point components call.
105
+ * The glyph to draw for a port.
106
+ *
107
+ * @deprecated since 2.4.0 — `SHAPE_GLYPH[portShape(checker, port)]`, which is
108
+ * what this is. Both it and the map went out in 2.3.0's public surface and only
109
+ * one of them needs to be there: the map is the vocabulary, and composing it is
110
+ * a lookup. Kept until 3.0.0 because removing a released export is not a minor.
95
111
  */
96
112
  export declare function portGlyph(checker: PortCompatibilityChecker, port: ShapedPort): string;
97
- /**
98
- * A human name for a port's shape, for the symbol's tooltip.
99
- */
100
- export declare function portShapeLabel(checker: PortCompatibilityChecker, port: ShapedPort): string;
101
113
  export {};
@@ -10,23 +10,33 @@
10
10
  *
11
11
  * ## Where the shape comes from
12
12
  *
13
- * The server's `NodePort` DTO carries no JSON Schema type today (`schema?` is
14
- * declared for template autocomplete and no producer populates it), so the
15
- * shape is derived client-side from the lane. Every lane FlowDrop ships implies
16
- * exactly one shape, so the map below answers the question against every
17
- * backend — including older fddo and third-party servers that only implement
18
- * the port-config endpoint.
19
- *
20
- * Two things the derivation cannot do, both known and accepted:
13
+ * Two sources, in this order:
14
+ *
15
+ * 1. **The lane's served schema** (`PortDataTypeConfig.schema`) — a JSON Schema
16
+ * the backend's shape registry declares for the lane. Its `type` IS the
17
+ * shape, said by the side that knows: fddo's `error` shape declares
18
+ * `type: object`, `messages` declares `type: array`, and a site's own
19
+ * `Order` shape answers for itself without the client having heard of it.
20
+ * 2. **The lane table below**, when no schema is served — which is every lane
21
+ * on an older fddo, on a third-party server implementing only the
22
+ * port-config endpoint, and on the library's offline defaults (which stay
23
+ * presentation-only on purpose and carry no schemas).
24
+ *
25
+ * The table was the whole answer before shapes reached the wire, and the
26
+ * ordering above is why the fallback stays: it is what draws a glyph when
27
+ * nothing declares one, not a second opinion competing with a served answer.
28
+ *
29
+ * Two things the fallback cannot do, both known and accepted:
21
30
  * - **`integer` vs `number` collapse.** The server already maps both onto lane
22
- * `number`, so nothing is lost that the client ever had.
23
- * - **A site-defined lane resolves to `unknown` (`?`).** A lane added through
24
- * the `port_config` overlay has no shape the client can know. `?` is the
25
- * honest answer.
31
+ * `number`, so nothing is lost that the client ever had. A served schema
32
+ * saying `integer` collapses the same way, for the same reason.
33
+ * - **A site-defined lane with no shape resolves to `unknown` (`?`).** A lane
34
+ * added through the `port_config` overlay alone has nothing to read. `?` is
35
+ * the honest answer, and declaring a shape for the lane is how a site
36
+ * improves it.
26
37
  *
27
- * {@link portShape} is the seam where that improves: a later release that
28
- * serves a shape per lane, or populates `NodePort.schema`, changes this one
29
- * function and no caller.
38
+ * {@link portShape} is the one function either source is read in, which is what
39
+ * kept adding the first source to a single place.
30
40
  *
31
41
  * It takes the **checker** for exactly that reason. Colour has always asked the
32
42
  * checker, which resolves an alias to its canonical lane and sees whatever the
@@ -78,8 +88,9 @@ export const SHAPE_LABEL = {
78
88
  * zero declaring ports, the schema-type→lane resolver
79
89
  * (`NodeMetadataResolver::mapSchemaTypeToDataType`) can never emit them, and no
80
90
  * fddo plan schedules a shape for them. "URI string" was a plausible guess with
81
- * nothing behind it, and a wrong glyph is worse than an honest `?`. Phase 2's
82
- * server-declared shape is how a site that does use them answers this.
91
+ * nothing behind it, and a wrong glyph is worse than an honest `?`. A site that
92
+ * does use them declares a shape for the lane, which {@link portShape} reads
93
+ * ahead of this table.
83
94
  *
84
95
  * The legacy spellings (`text`, `list`, `integer`, `float`, `object`,
85
96
  * `document`, `picture`, `sound`, `movie`, `branch`) are here because
@@ -145,6 +156,34 @@ const LANE_SHAPE = {
145
156
  * port config, which is what stops a new lane shipping without a glyph.
146
157
  */
147
158
  export const LANE_SHAPES = LANE_SHAPE;
159
+ /**
160
+ * JSON Schema `type` → shape, for reading a lane's served schema.
161
+ *
162
+ * `integer` collapses onto `number` exactly as the server's own lane mapping
163
+ * does, so a shape declaring `integer` and a port on lane `number` draw the same
164
+ * `#`. `null` is deliberately absent: a lane whose schema promises only `null`
165
+ * has no shape worth a glyph, and falling through to the table is the better
166
+ * answer than inventing one.
167
+ */
168
+ const SCHEMA_TYPE_SHAPE = {
169
+ string: 'string',
170
+ number: 'number',
171
+ integer: 'number',
172
+ boolean: 'boolean',
173
+ array: 'array',
174
+ object: 'object'
175
+ };
176
+ /**
177
+ * The shape a served schema declares, or `undefined` when it declares none —
178
+ * which includes a schema with no `type` at all (`{properties: {…}}` alone, or
179
+ * a bare `$ref`), because the shape is the `type` and nothing else in the
180
+ * keyword space is being guessed at.
181
+ */
182
+ function schemaShape(schema) {
183
+ if (!schema?.type)
184
+ return undefined;
185
+ return SCHEMA_TYPE_SHAPE[schema.type.toLowerCase()];
186
+ }
148
187
  /**
149
188
  * The shape a lane id implies, straight from the table. `unknown` for any lane
150
189
  * not in it, including every site-defined one.
@@ -161,25 +200,25 @@ export function laneShape(dataType) {
161
200
  return LANE_SHAPE[dataType.toLowerCase()] ?? 'unknown';
162
201
  }
163
202
  /**
164
- * The shape to draw for a port — the seam described at the top of this file.
203
+ * The shape to draw for a port — both sources, in the order the top of this
204
+ * file states: the lane's served schema, then the table.
165
205
  *
166
- * Resolves the lane through the checker before consulting the table, so an
167
- * alias (`text` declared as an alias of `string`) is shaped as the lane it
168
- * aliases rather than as an unknown of its own.
206
+ * The lane is resolved through the checker either way, so an alias (`text`
207
+ * declared as an alias of `string`) reads the schema and the table of the lane
208
+ * it aliases rather than answering as an unknown of its own.
169
209
  */
170
210
  export function portShape(checker, port) {
171
- const canonical = port.dataType ? checker.getDataTypeConfig(port.dataType)?.id : undefined;
172
- return laneShape(canonical ?? port.dataType);
211
+ const lane = port.dataType ? checker.getDataTypeConfig(port.dataType) : undefined;
212
+ return schemaShape(lane?.schema) ?? laneShape(lane?.id ?? port.dataType);
173
213
  }
174
214
  /**
175
- * The glyph to draw for a port — the single entry point components call.
215
+ * The glyph to draw for a port.
216
+ *
217
+ * @deprecated since 2.4.0 — `SHAPE_GLYPH[portShape(checker, port)]`, which is
218
+ * what this is. Both it and the map went out in 2.3.0's public surface and only
219
+ * one of them needs to be there: the map is the vocabulary, and composing it is
220
+ * a lookup. Kept until 3.0.0 because removing a released export is not a minor.
176
221
  */
177
222
  export function portGlyph(checker, port) {
178
223
  return SHAPE_GLYPH[portShape(checker, port)];
179
224
  }
180
- /**
181
- * A human name for a port's shape, for the symbol's tooltip.
182
- */
183
- export function portShapeLabel(checker, port) {
184
- return SHAPE_LABEL[portShape(checker, port)];
185
- }
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "description": "A drop-in visual workflow editor for any web application. You own the backend. You own the data. You own the orchestration.",
4
4
  "license": "MIT",
5
5
  "private": false,
6
- "version": "2.3.0",
6
+ "version": "2.4.0",
7
7
  "author": "Shibin Das (D34dMan)",
8
8
  "bugs": {
9
9
  "url": "https://github.com/flowdrop-io/flowdrop/issues"