@flowdrop/flowdrop 2.2.2 → 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.
@@ -0,0 +1,224 @@
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
+ * 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:
30
+ * - **`integer` vs `number` collapse.** The server already maps both onto lane
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.
37
+ *
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.
40
+ *
41
+ * It takes the **checker** for exactly that reason. Colour has always asked the
42
+ * checker, which resolves an alias to its canonical lane and sees whatever the
43
+ * backend served; a private lookup table cannot do either, so the same port got
44
+ * a lane colour and a shapeless `?` at the same time. Routing shape through the
45
+ * same source makes that class of disagreement unrepresentable, and means a
46
+ * served shape lands here without touching a call site.
47
+ */
48
+ /**
49
+ * The glyph shown for each shape. Deliberately tiny and ASCII: `{}` and `[]`
50
+ * are the notation a developer already reads as object and array, and the
51
+ * bracket idiom extends to `()` for a callable.
52
+ *
53
+ * `number` is `#` and not `I`, because the lane it renders covers floats —
54
+ * `I` would be a lie on `Temperature: 0.7`. If a future release splits
55
+ * `integer` out, `I` joins the set and `#` keeps meaning "number".
56
+ */
57
+ export const SHAPE_GLYPH = {
58
+ string: 'S',
59
+ number: '#',
60
+ boolean: 'B',
61
+ array: '[]',
62
+ object: '{}',
63
+ unknown: '?',
64
+ trigger: 'T',
65
+ callable: '()'
66
+ };
67
+ /**
68
+ * A human-readable name per shape, for the symbol's tooltip. The glyph is a
69
+ * compression for the eye; this is what it decompresses to.
70
+ */
71
+ export const SHAPE_LABEL = {
72
+ string: 'text',
73
+ number: 'number',
74
+ boolean: 'true/false',
75
+ array: 'list',
76
+ object: 'object',
77
+ unknown: 'unknown shape',
78
+ trigger: 'trigger signal',
79
+ callable: 'callable'
80
+ };
81
+ /**
82
+ * Lane id → shape, for every lane the library ships (see
83
+ * `config/defaultPortConfig.ts`, which this table is total over — a lane added
84
+ * there without an entry here fails `tests/unit/utils/portShape.test.ts`).
85
+ *
86
+ * The media lanes (`file`, `image`, `audio`, `video`) are `unknown`, not
87
+ * `string`. Asked directly, fddo has no answer: they are served vocabulary with
88
+ * zero declaring ports, the schema-type→lane resolver
89
+ * (`NodeMetadataResolver::mapSchemaTypeToDataType`) can never emit them, and no
90
+ * fddo plan schedules a shape for them. "URI string" was a plausible guess with
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.
94
+ *
95
+ * The legacy spellings (`text`, `list`, `integer`, `float`, `object`,
96
+ * `document`, `picture`, `sound`, `movie`, `branch`) are here because
97
+ * `colors.ts` still gives them a colour. Two tables answering about the same
98
+ * lane must answer together — `portShape.test.ts` asserts this one is total
99
+ * over that one.
100
+ *
101
+ * `messages` is `array` — a list of provider-shaped chat messages. Its colour
102
+ * still comes from its own lane, which is the whole point of separating the
103
+ * two channels: teal chip, `[]` glyph, no contradiction.
104
+ */
105
+ const LANE_SHAPE = {
106
+ // Text and text-shaped scalars.
107
+ string: 'string',
108
+ text: 'string',
109
+ url: 'string',
110
+ email: 'string',
111
+ date: 'string',
112
+ datetime: 'string',
113
+ time: 'string',
114
+ // Numeric — `integer` and `float` are server-side spellings the payload
115
+ // collapses onto `number`, kept here because the fallback colour map still
116
+ // names them.
117
+ number: 'number',
118
+ integer: 'number',
119
+ float: 'number',
120
+ boolean: 'boolean',
121
+ // Collections.
122
+ array: 'array',
123
+ list: 'array',
124
+ 'string[]': 'array',
125
+ 'number[]': 'array',
126
+ 'boolean[]': 'array',
127
+ 'json[]': 'array',
128
+ 'file[]': 'array',
129
+ 'image[]': 'array',
130
+ messages: 'array',
131
+ // Structured.
132
+ json: 'object',
133
+ object: 'object',
134
+ // Media: served vocabulary with no declared shape anywhere. See above.
135
+ file: 'unknown',
136
+ image: 'unknown',
137
+ audio: 'unknown',
138
+ video: 'unknown',
139
+ document: 'unknown',
140
+ picture: 'unknown',
141
+ sound: 'unknown',
142
+ movie: 'unknown',
143
+ // The sink, and its retired second spelling: a port that constrains nothing
144
+ // has no shape to show.
145
+ mixed: 'unknown',
146
+ any: 'unknown',
147
+ // Control lanes. `branch` is the legacy spelling of a gateway's outgoing
148
+ // control path — same signal, older word.
149
+ trigger: 'trigger',
150
+ branch: 'trigger',
151
+ tool: 'callable'
152
+ };
153
+ /**
154
+ * Read-only view of the lane table. Not part of the package's public exports —
155
+ * it exists so the test suite can assert the table is total over the shipped
156
+ * port config, which is what stops a new lane shipping without a glyph.
157
+ */
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
+ }
187
+ /**
188
+ * The shape a lane id implies, straight from the table. `unknown` for any lane
189
+ * not in it, including every site-defined one.
190
+ *
191
+ * Case-insensitive, because `getDataTypeColorToken` is: a backend that spells
192
+ * its lane `String` gets a colour, and must not then get a shapeless `?`.
193
+ *
194
+ * This is the offline half. Prefer {@link portShape}, which consults the served
195
+ * vocabulary first.
196
+ */
197
+ export function laneShape(dataType) {
198
+ if (!dataType)
199
+ return 'unknown';
200
+ return LANE_SHAPE[dataType.toLowerCase()] ?? 'unknown';
201
+ }
202
+ /**
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.
205
+ *
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.
209
+ */
210
+ export function portShape(checker, port) {
211
+ const lane = port.dataType ? checker.getDataTypeConfig(port.dataType) : undefined;
212
+ return schemaShape(lane?.schema) ?? laneShape(lane?.id ?? port.dataType);
213
+ }
214
+ /**
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.
221
+ */
222
+ export function portGlyph(checker, port) {
223
+ return SHAPE_GLYPH[portShape(checker, port)];
224
+ }
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.4.0",
7
7
  "author": "Shibin Das (D34dMan)",
8
8
  "bugs": {
9
9
  "url": "https://github.com/flowdrop-io/flowdrop/issues"