@flowdrop/flowdrop 2.2.2 → 2.3.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.
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Port shape symbols — what shape a port carries, said separately from which
3
+ * lane it belongs to.
4
+ *
5
+ * A port row shows two independent facts: its JSON-Schema **shape** (is this a
6
+ * string, a list, an object?) and its semantic **lane** (`messages`, `url`,
7
+ * `tool`). Colour used to carry both, so it carried neither well. The shape
8
+ * moves to a small glyph; the lane keeps its id in a quiet outlined chip and
9
+ * keeps the colour.
10
+ *
11
+ * ## Where the shape comes from
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:
21
+ * - **`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.
26
+ *
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.
30
+ *
31
+ * It takes the **checker** for exactly that reason. Colour has always asked the
32
+ * checker, which resolves an alias to its canonical lane and sees whatever the
33
+ * backend served; a private lookup table cannot do either, so the same port got
34
+ * a lane colour and a shapeless `?` at the same time. Routing shape through the
35
+ * same source makes that class of disagreement unrepresentable, and means a
36
+ * served shape lands here without touching a call site.
37
+ */
38
+ import type { PortCompatibilityChecker } from './connections.js';
39
+ /**
40
+ * The closed shape vocabulary. One glyph each, and every lane resolves to
41
+ * exactly one of these.
42
+ *
43
+ * `trigger` and `callable` are not JSON-Schema shapes — they are the two
44
+ * control lanes, whose payload is a signal and a callable respectively. They
45
+ * get their own marks because rendering either as `?` would hide the one thing
46
+ * a reader needs to know about them.
47
+ */
48
+ export type PortShape = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'unknown' | 'trigger' | 'callable';
49
+ /**
50
+ * The glyph shown for each shape. Deliberately tiny and ASCII: `{}` and `[]`
51
+ * are the notation a developer already reads as object and array, and the
52
+ * bracket idiom extends to `()` for a callable.
53
+ *
54
+ * `number` is `#` and not `I`, because the lane it renders covers floats —
55
+ * `I` would be a lie on `Temperature: 0.7`. If a future release splits
56
+ * `integer` out, `I` joins the set and `#` keeps meaning "number".
57
+ */
58
+ export declare const SHAPE_GLYPH: Record<PortShape, string>;
59
+ /**
60
+ * A human-readable name per shape, for the symbol's tooltip. The glyph is a
61
+ * compression for the eye; this is what it decompresses to.
62
+ */
63
+ export declare const SHAPE_LABEL: Record<PortShape, string>;
64
+ /**
65
+ * Read-only view of the lane table. Not part of the package's public exports —
66
+ * it exists so the test suite can assert the table is total over the shipped
67
+ * port config, which is what stops a new lane shipping without a glyph.
68
+ */
69
+ export declare const LANE_SHAPES: Readonly<Record<string, PortShape>>;
70
+ /** The port fields shape derivation reads. */
71
+ interface ShapedPort {
72
+ dataType?: string;
73
+ }
74
+ /**
75
+ * The shape a lane id implies, straight from the table. `unknown` for any lane
76
+ * not in it, including every site-defined one.
77
+ *
78
+ * Case-insensitive, because `getDataTypeColorToken` is: a backend that spells
79
+ * its lane `String` gets a colour, and must not then get a shapeless `?`.
80
+ *
81
+ * This is the offline half. Prefer {@link portShape}, which consults the served
82
+ * vocabulary first.
83
+ */
84
+ export declare function laneShape(dataType: string | undefined): PortShape;
85
+ /**
86
+ * The shape to draw for a port — the seam described at the top of this file.
87
+ *
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.
91
+ */
92
+ export declare function portShape(checker: PortCompatibilityChecker, port: ShapedPort): PortShape;
93
+ /**
94
+ * The glyph to draw for a port — the single entry point components call.
95
+ */
96
+ 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
+ export {};
@@ -0,0 +1,185 @@
1
+ /**
2
+ * Port shape symbols — what shape a port carries, said separately from which
3
+ * lane it belongs to.
4
+ *
5
+ * A port row shows two independent facts: its JSON-Schema **shape** (is this a
6
+ * string, a list, an object?) and its semantic **lane** (`messages`, `url`,
7
+ * `tool`). Colour used to carry both, so it carried neither well. The shape
8
+ * moves to a small glyph; the lane keeps its id in a quiet outlined chip and
9
+ * keeps the colour.
10
+ *
11
+ * ## Where the shape comes from
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:
21
+ * - **`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.
26
+ *
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.
30
+ *
31
+ * It takes the **checker** for exactly that reason. Colour has always asked the
32
+ * checker, which resolves an alias to its canonical lane and sees whatever the
33
+ * backend served; a private lookup table cannot do either, so the same port got
34
+ * a lane colour and a shapeless `?` at the same time. Routing shape through the
35
+ * same source makes that class of disagreement unrepresentable, and means a
36
+ * served shape lands here without touching a call site.
37
+ */
38
+ /**
39
+ * The glyph shown for each shape. Deliberately tiny and ASCII: `{}` and `[]`
40
+ * are the notation a developer already reads as object and array, and the
41
+ * bracket idiom extends to `()` for a callable.
42
+ *
43
+ * `number` is `#` and not `I`, because the lane it renders covers floats —
44
+ * `I` would be a lie on `Temperature: 0.7`. If a future release splits
45
+ * `integer` out, `I` joins the set and `#` keeps meaning "number".
46
+ */
47
+ export const SHAPE_GLYPH = {
48
+ string: 'S',
49
+ number: '#',
50
+ boolean: 'B',
51
+ array: '[]',
52
+ object: '{}',
53
+ unknown: '?',
54
+ trigger: 'T',
55
+ callable: '()'
56
+ };
57
+ /**
58
+ * A human-readable name per shape, for the symbol's tooltip. The glyph is a
59
+ * compression for the eye; this is what it decompresses to.
60
+ */
61
+ export const SHAPE_LABEL = {
62
+ string: 'text',
63
+ number: 'number',
64
+ boolean: 'true/false',
65
+ array: 'list',
66
+ object: 'object',
67
+ unknown: 'unknown shape',
68
+ trigger: 'trigger signal',
69
+ callable: 'callable'
70
+ };
71
+ /**
72
+ * Lane id → shape, for every lane the library ships (see
73
+ * `config/defaultPortConfig.ts`, which this table is total over — a lane added
74
+ * there without an entry here fails `tests/unit/utils/portShape.test.ts`).
75
+ *
76
+ * The media lanes (`file`, `image`, `audio`, `video`) are `unknown`, not
77
+ * `string`. Asked directly, fddo has no answer: they are served vocabulary with
78
+ * zero declaring ports, the schema-type→lane resolver
79
+ * (`NodeMetadataResolver::mapSchemaTypeToDataType`) can never emit them, and no
80
+ * 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.
83
+ *
84
+ * The legacy spellings (`text`, `list`, `integer`, `float`, `object`,
85
+ * `document`, `picture`, `sound`, `movie`, `branch`) are here because
86
+ * `colors.ts` still gives them a colour. Two tables answering about the same
87
+ * lane must answer together — `portShape.test.ts` asserts this one is total
88
+ * over that one.
89
+ *
90
+ * `messages` is `array` — a list of provider-shaped chat messages. Its colour
91
+ * still comes from its own lane, which is the whole point of separating the
92
+ * two channels: teal chip, `[]` glyph, no contradiction.
93
+ */
94
+ const LANE_SHAPE = {
95
+ // Text and text-shaped scalars.
96
+ string: 'string',
97
+ text: 'string',
98
+ url: 'string',
99
+ email: 'string',
100
+ date: 'string',
101
+ datetime: 'string',
102
+ time: 'string',
103
+ // Numeric — `integer` and `float` are server-side spellings the payload
104
+ // collapses onto `number`, kept here because the fallback colour map still
105
+ // names them.
106
+ number: 'number',
107
+ integer: 'number',
108
+ float: 'number',
109
+ boolean: 'boolean',
110
+ // Collections.
111
+ array: 'array',
112
+ list: 'array',
113
+ 'string[]': 'array',
114
+ 'number[]': 'array',
115
+ 'boolean[]': 'array',
116
+ 'json[]': 'array',
117
+ 'file[]': 'array',
118
+ 'image[]': 'array',
119
+ messages: 'array',
120
+ // Structured.
121
+ json: 'object',
122
+ object: 'object',
123
+ // Media: served vocabulary with no declared shape anywhere. See above.
124
+ file: 'unknown',
125
+ image: 'unknown',
126
+ audio: 'unknown',
127
+ video: 'unknown',
128
+ document: 'unknown',
129
+ picture: 'unknown',
130
+ sound: 'unknown',
131
+ movie: 'unknown',
132
+ // The sink, and its retired second spelling: a port that constrains nothing
133
+ // has no shape to show.
134
+ mixed: 'unknown',
135
+ any: 'unknown',
136
+ // Control lanes. `branch` is the legacy spelling of a gateway's outgoing
137
+ // control path — same signal, older word.
138
+ trigger: 'trigger',
139
+ branch: 'trigger',
140
+ tool: 'callable'
141
+ };
142
+ /**
143
+ * Read-only view of the lane table. Not part of the package's public exports —
144
+ * it exists so the test suite can assert the table is total over the shipped
145
+ * port config, which is what stops a new lane shipping without a glyph.
146
+ */
147
+ export const LANE_SHAPES = LANE_SHAPE;
148
+ /**
149
+ * The shape a lane id implies, straight from the table. `unknown` for any lane
150
+ * not in it, including every site-defined one.
151
+ *
152
+ * Case-insensitive, because `getDataTypeColorToken` is: a backend that spells
153
+ * its lane `String` gets a colour, and must not then get a shapeless `?`.
154
+ *
155
+ * This is the offline half. Prefer {@link portShape}, which consults the served
156
+ * vocabulary first.
157
+ */
158
+ export function laneShape(dataType) {
159
+ if (!dataType)
160
+ return 'unknown';
161
+ return LANE_SHAPE[dataType.toLowerCase()] ?? 'unknown';
162
+ }
163
+ /**
164
+ * The shape to draw for a port — the seam described at the top of this file.
165
+ *
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.
169
+ */
170
+ export function portShape(checker, port) {
171
+ const canonical = port.dataType ? checker.getDataTypeConfig(port.dataType)?.id : undefined;
172
+ return laneShape(canonical ?? port.dataType);
173
+ }
174
+ /**
175
+ * The glyph to draw for a port — the single entry point components call.
176
+ */
177
+ export function portGlyph(checker, port) {
178
+ return SHAPE_GLYPH[portShape(checker, port)];
179
+ }
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.2.2",
6
+ "version": "2.3.0",
7
7
  "author": "Shibin Das (D34dMan)",
8
8
  "bugs": {
9
9
  "url": "https://github.com/flowdrop-io/flowdrop/issues"