embedded-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.
Files changed (140) hide show
  1. package/NOTICE +5 -0
  2. package/README.md +3 -2
  3. package/aot/app-file-loader.mjs +116 -0
  4. package/aot/compile.mjs +17 -47
  5. package/aot/compiler/alerts.mjs +604 -0
  6. package/aot/compiler/animations.mjs +299 -57
  7. package/aot/compiler/boot.mjs +27 -2
  8. package/aot/compiler/check.mjs +62 -10
  9. package/aot/compiler/collect.mjs +517 -137
  10. package/aot/compiler/contexts.mjs +391 -0
  11. package/aot/compiler/control-flow.mjs +276 -117
  12. package/aot/compiler/custom-hooks.mjs +686 -0
  13. package/aot/compiler/elements/button.mjs +182 -0
  14. package/aot/compiler/elements/image-background.mjs +76 -0
  15. package/aot/compiler/elements/image.mjs +2 -1
  16. package/aot/compiler/elements/props.mjs +47 -8
  17. package/aot/compiler/elements/rewrite.mjs +118 -0
  18. package/aot/compiler/elements/section-list.mjs +370 -0
  19. package/aot/compiler/expressions.mjs +1378 -97
  20. package/aot/compiler/handlers.mjs +1807 -354
  21. package/aot/compiler/helper-values.mjs +312 -0
  22. package/aot/compiler/ir/nodes.mjs +40 -1
  23. package/aot/compiler/ir/reads.mjs +206 -5
  24. package/aot/compiler/ir/text.mjs +5 -1
  25. package/aot/compiler/ir/types.mjs +12 -0
  26. package/aot/compiler/kept-states.mjs +177 -0
  27. package/aot/compiler/keyboard-dismiss.mjs +99 -0
  28. package/aot/compiler/keyboard.mjs +1 -1
  29. package/aot/compiler/list-items.mjs +226 -0
  30. package/aot/compiler/list-order.mjs +586 -0
  31. package/aot/compiler/list-split.mjs +259 -0
  32. package/aot/compiler/loops.mjs +582 -0
  33. package/aot/compiler/lower.mjs +203 -53
  34. package/aot/compiler/native-files.mjs +439 -0
  35. package/aot/compiler/native-header.mjs +335 -0
  36. package/aot/compiler/native-modules.mjs +1173 -0
  37. package/aot/compiler/nodes.mjs +45 -31
  38. package/aot/compiler/options.mjs +3 -2
  39. package/aot/compiler/out.mjs +18 -1
  40. package/aot/compiler/package/animations.mjs +133 -23
  41. package/aot/compiler/package/assemble.mjs +2 -4
  42. package/aot/compiler/package/bytecode.mjs +37 -8
  43. package/aot/compiler/package/checks.mjs +4 -0
  44. package/aot/compiler/package/codegen.mjs +906 -33
  45. package/aot/compiler/package/enums.mjs +10 -0
  46. package/aot/compiler/package/format.mjs +16 -3
  47. package/aot/compiler/package/lower.mjs +707 -176
  48. package/aot/compiler/package/string-caps.mjs +515 -0
  49. package/aot/compiler/package/tables.mjs +24 -0
  50. package/aot/compiler/package/writer.mjs +22 -0
  51. package/aot/compiler/parse.mjs +3 -1
  52. package/aot/compiler/record-shapes.mjs +246 -0
  53. package/aot/compiler/records.mjs +654 -0
  54. package/aot/compiler/reducers.mjs +272 -0
  55. package/aot/compiler/scroll-to.mjs +112 -0
  56. package/aot/compiler/static-eval.mjs +315 -7
  57. package/aot/compiler/style-text.mjs +20 -5
  58. package/aot/compiler/svg.mjs +13 -7
  59. package/aot/compiler/switch-cases.mjs +198 -0
  60. package/aot/compiler/tagged-records.mjs +450 -0
  61. package/aot/compiler/typing.mjs +307 -0
  62. package/aot/compiler/updaters.mjs +321 -0
  63. package/aot/compiler/window-dimensions.mjs +94 -0
  64. package/aot/compiler/worked-values.mjs +319 -0
  65. package/aot/demo-file.mjs +30 -0
  66. package/aot/style-map.mjs +94 -3
  67. package/assets/bake-font.mjs +187 -244
  68. package/assets/bake-image.mjs +47 -71
  69. package/assets/bake-svg.mjs +465 -533
  70. package/assets/build-builtin-font.mjs +14 -27
  71. package/assets/emit-c.mjs +124 -204
  72. package/assets/emit-container.mjs +129 -197
  73. package/assets/emit-pack.mjs +92 -136
  74. package/assets/font-config.mjs +19 -27
  75. package/assets/font-sizes.mjs +432 -507
  76. package/assets/glyph-coverage.mjs +170 -214
  77. package/assets/index.mjs +52 -97
  78. package/assets/rasterize.mjs +173 -194
  79. package/assets/svg-loader.mjs +42 -48
  80. package/build.mjs +85 -94
  81. package/cli.mjs +490 -586
  82. package/compile-bin.mjs +24 -36
  83. package/flash.mjs +297 -401
  84. package/hotreload/dev-device.mjs +229 -270
  85. package/hotreload/pack-app.mjs +118 -159
  86. package/hotreload/pack-split.mjs +146 -213
  87. package/hotreload/package-transfer.mjs +128 -131
  88. package/hotreload/protocol.mjs +118 -118
  89. package/hotreload/uploader.mjs +132 -159
  90. package/hotreload/watch-tree.mjs +56 -65
  91. package/pack-container.mjs +94 -116
  92. package/package.json +19 -16
  93. package/persist-transform.mjs +89 -105
  94. package/qjsc-wasm.mjs +47 -72
  95. package/sim/embedded-react.wasm +0 -0
  96. package/sim/index.html +1 -1
  97. package/sim-server.mjs +260 -354
  98. package/src/embedded-react/Alert.mjs +112 -0
  99. package/src/embedded-react/Animated.mjs +412 -0
  100. package/src/embedded-react/{AppRegistry.js → AppRegistry.mjs} +26 -25
  101. package/src/embedded-react/{Button.js → Button.mjs} +29 -53
  102. package/src/embedded-react/Dimensions.mjs +32 -0
  103. package/src/embedded-react/Easing.mjs +34 -0
  104. package/src/embedded-react/{FlatList.js → FlatList.mjs} +25 -42
  105. package/src/embedded-react/{ImageBackground.js → ImageBackground.mjs} +11 -22
  106. package/src/embedded-react/Keyboard.mjs +82 -0
  107. package/src/embedded-react/{LayoutAnimation.js → LayoutAnimation.mjs} +17 -28
  108. package/src/embedded-react/PanResponder.mjs +256 -0
  109. package/src/embedded-react/{Platform.js → Platform.mjs} +8 -9
  110. package/src/embedded-react/{Pressable.js → Pressable.mjs} +12 -25
  111. package/src/embedded-react/SectionList.mjs +103 -0
  112. package/src/embedded-react/{StyleSheet.js → StyleSheet.mjs} +16 -20
  113. package/src/embedded-react/{TouchableOpacity.js → TouchableOpacity.mjs} +47 -83
  114. package/src/embedded-react/background-image.mjs +321 -0
  115. package/src/embedded-react/{components.js → components.mjs} +1 -3
  116. package/src/embedded-react/{imperative.js → imperative.mjs} +27 -38
  117. package/src/embedded-react/index.d.ts +238 -5
  118. package/src/embedded-react/index.js +26 -17
  119. package/src/embedded-react/layout-anim-config.mjs +85 -0
  120. package/src/embedded-react/{list-child.js → list-child.mjs} +11 -20
  121. package/src/embedded-react/{named-colors.js → named-colors.mjs} +2 -6
  122. package/src/embedded-react/nativeModule.mjs +371 -0
  123. package/src/embedded-react/split-style.mjs +57 -0
  124. package/src/embedded-react/svg-ops.mjs +1075 -0
  125. package/src/embedded-react/{useHostValue.js → useHostValue.mjs} +2 -4
  126. package/src/embedded-react/{usePersistentState.js → usePersistentState.mjs} +34 -38
  127. package/src/embedded-react/{warn-props.js → warn-props.mjs} +32 -39
  128. package/src/host-config.mjs +512 -0
  129. package/src/{native-ui.js → native-ui.mjs} +1 -8
  130. package/src/props.mjs +341 -0
  131. package/src/{renderer.js → renderer.mjs} +30 -44
  132. package/src/embedded-react/Animated.js +0 -440
  133. package/src/embedded-react/Easing.js +0 -39
  134. package/src/embedded-react/PanResponder.js +0 -330
  135. package/src/embedded-react/SectionList.js +0 -148
  136. package/src/embedded-react/layout-anim-config.js +0 -101
  137. package/src/embedded-react/split-style.js +0 -58
  138. package/src/embedded-react/svg-ops.js +0 -1295
  139. package/src/host-config.js +0 -548
  140. package/src/props.js +0 -306
@@ -0,0 +1,321 @@
1
+ /*
2
+ * Copyright 2026 Cory Lamming
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ */
16
+ /*----------------------------------------------------------------------------------------------------------------------
17
+ - Constants
18
+ ---------------------------------------------------------------------------------------------------------------------*/
19
+ /** The engine's ER_GRADIENT_MAX_STOPS. */
20
+ export const BACKGROUND_MAX_STOPS = 4;
21
+ /** CSS degrees of each side: 0 points to the top, 90 to the right. */
22
+ const SIDE_ANGLES = {
23
+ top: 0,
24
+ right: 90,
25
+ bottom: 180,
26
+ left: 270,
27
+ };
28
+ /** ERGradientCorner of each corner, by its vertical then horizontal side. */
29
+ const CORNERS = {
30
+ 'top right': 1,
31
+ 'bottom right': 2,
32
+ 'bottom left': 3,
33
+ 'top left': 4,
34
+ };
35
+ /** Degrees in one of each CSS angle unit. */
36
+ const ANGLE_UNITS = {
37
+ deg: 1,
38
+ grad: 0.9,
39
+ rad: 180 / Math.PI,
40
+ turn: 360,
41
+ };
42
+ /** The characters a number starts with. */
43
+ const NUMBER_START = '0123456789.+-';
44
+ /*----------------------------------------------------------------------------------------------------------------------
45
+ - Implementation
46
+ ---------------------------------------------------------------------------------------------------------------------*/
47
+ // The parser uses no regular expressions: each costs bytecode in every Flow A bundle, and a case-insensitive
48
+ // one costs kilobytes. A problem is thrown as its message.
49
+ /**
50
+ * Refuses a value the engine does not draw.
51
+ *
52
+ * @param message What is wrong with it.
53
+ */
54
+ function refuse(message) {
55
+ throw message;
56
+ }
57
+ /**
58
+ * Splits text at a separator, leaving what is inside parentheses whole.
59
+ *
60
+ * @param text The text.
61
+ * @param separator `,` or a space, which stands for any run of whitespace.
62
+ *
63
+ * @returns The parts, trimmed, with no empty ones.
64
+ */
65
+ function splitOutside(text, separator) {
66
+ const parts = [];
67
+ let depth = 0;
68
+ let part = '';
69
+ // By index: a for...of over a string never ends on the ESP32's QuickJS.
70
+ for (let index = 0; index < text.length; index++) {
71
+ const character = text[index];
72
+ if (character === '(')
73
+ depth++;
74
+ if (character === ')')
75
+ depth--;
76
+ // Whitespace sorts at or below the space.
77
+ if (depth === 0 &&
78
+ (separator === ',' ? character === ',' : character <= ' ')) {
79
+ parts.push(part);
80
+ part = '';
81
+ }
82
+ else {
83
+ part += character;
84
+ }
85
+ }
86
+ parts.push(part);
87
+ return parts.map(entry => entry.trim()).filter(entry => entry !== '');
88
+ }
89
+ /**
90
+ * A number with a unit after it.
91
+ *
92
+ * @param text The text.
93
+ * @param unit The unit it must end with.
94
+ *
95
+ * @returns The number, or NaN when the text is not one.
96
+ */
97
+ function numberWith(text, unit) {
98
+ const digits = text.slice(0, -unit.length);
99
+ return text.endsWith(unit) && digits !== '' ? Number(digits) : NaN;
100
+ }
101
+ /**
102
+ * A `direction`: an angle, or `to` a side or corner.
103
+ *
104
+ * @param direction The direction, lowercase.
105
+ *
106
+ * @returns The engine's angle and corner, or null when it is not a direction.
107
+ */
108
+ function parseDirection(direction) {
109
+ let cssDegrees = NaN;
110
+ if (direction.startsWith('to ')) {
111
+ const sides = splitOutside(direction.slice(3), ' ');
112
+ // Either order names the corner.
113
+ const corner = CORNERS[`${sides[0]} ${sides[1]}`] ?? CORNERS[`${sides[1]} ${sides[0]}`];
114
+ if (sides.length === 2 && corner)
115
+ return { angle: 0, corner };
116
+ if (sides.length !== 1 || !Object.hasOwn(SIDE_ANGLES, sides[0])) {
117
+ refuse(`"${direction}" is not a direction`);
118
+ }
119
+ cssDegrees = SIDE_ANGLES[sides[0]];
120
+ }
121
+ else {
122
+ // `grad` is tried before `rad`, which it ends with.
123
+ for (const unit in ANGLE_UNITS) {
124
+ if (Number.isNaN(cssDegrees)) {
125
+ cssDegrees = numberWith(direction, unit) * ANGLE_UNITS[unit];
126
+ }
127
+ }
128
+ if (Number.isNaN(cssDegrees))
129
+ return null;
130
+ }
131
+ // CSS 0 points to the top and the engine's 0 to the bottom; both turn clockwise.
132
+ return { angle: (((180 - cssDegrees) % 360) + 360) % 360, corner: 0 };
133
+ }
134
+ /**
135
+ * A stop's position.
136
+ *
137
+ * @param position A percentage.
138
+ *
139
+ * @returns It as 0 to 1.
140
+ */
141
+ function parsePosition(position) {
142
+ const offset = typeof position === 'string' ? numberWith(position.trim(), '%') / 100 : NaN;
143
+ if (Number.isNaN(offset)) {
144
+ refuse(`a stop position must be a percentage, got ${JSON.stringify(position)}`);
145
+ }
146
+ if (offset < 0 || offset > 1) {
147
+ refuse(`a stop position must be 0% to 100%, got ${position}`);
148
+ }
149
+ return offset;
150
+ }
151
+ /**
152
+ * Settles every stop's offset as CSS does: the ends default to 0 and 1, a stop without one sits evenly between
153
+ * its neighbours, and one below an earlier stop is raised to it.
154
+ *
155
+ * @param pending The stops as written.
156
+ *
157
+ * @returns The stops.
158
+ */
159
+ function settleStops(pending) {
160
+ if (pending.length < 2 || pending.length > BACKGROUND_MAX_STOPS) {
161
+ refuse(`a gradient takes 2 to ${BACKGROUND_MAX_STOPS} stops, got ${pending.length}`);
162
+ }
163
+ const offsets = pending.map(stop => stop.offset);
164
+ offsets[0] ??= 0;
165
+ offsets[offsets.length - 1] ??= 1;
166
+ let highest = 0;
167
+ for (let index = 0; index < offsets.length; index++) {
168
+ if (offsets[index] !== null) {
169
+ highest = offsets[index] = Math.max(offsets[index], highest);
170
+ }
171
+ }
172
+ for (let index = 1; index < offsets.length; index++) {
173
+ if (offsets[index] !== null)
174
+ continue;
175
+ let next = index;
176
+ while (offsets[next] === null)
177
+ next++;
178
+ const before = offsets[index - 1];
179
+ const step = (offsets[next] - before) / (next - index + 1);
180
+ for (let fill = index; fill < next; fill++) {
181
+ offsets[fill] = before + step * (fill - index + 1);
182
+ }
183
+ }
184
+ return pending.map((stop, index) => ({
185
+ color: stop.color,
186
+ offset: offsets[index],
187
+ }));
188
+ }
189
+ /**
190
+ * Checks a radial gradient is the one the engine draws: a circle to the farthest corner, from the centre.
191
+ *
192
+ * @param shape `circle`, or with a size and position after it, lowercase.
193
+ */
194
+ function checkRadial(shape) {
195
+ const rest = splitOutside(shape, ' ')
196
+ .filter(word => word !== 'farthest-corner')
197
+ .join(' ');
198
+ if (![
199
+ 'circle',
200
+ 'circle at center',
201
+ 'circle at center center',
202
+ 'circle at 50% 50%',
203
+ ].includes(rest)) {
204
+ refuse('a radial gradient must be `circle`, to the farthest corner, at the center');
205
+ }
206
+ }
207
+ /**
208
+ * A CSS gradient function.
209
+ *
210
+ * @param text `linear-gradient(...)` or `radial-gradient(...)`.
211
+ *
212
+ * @returns The gradient.
213
+ */
214
+ function parseString(text) {
215
+ // Colors and keywords read the same in any case.
216
+ const lower = text.trim().toLowerCase();
217
+ const type = lower.startsWith('linear') ? 'linear' : 'radial';
218
+ if (splitOutside(lower, ',').length > 1)
219
+ refuse('a View takes one gradient');
220
+ if (!lower.startsWith(`${type}-gradient(`) || !lower.endsWith(')')) {
221
+ refuse('expected linear-gradient(...) or radial-gradient(...)');
222
+ }
223
+ const parts = splitOutside(lower.slice(type.length + 10, -1), ',');
224
+ let direction = { angle: 0, corner: 0 };
225
+ const first = parts[0] ?? '';
226
+ if (type === 'linear') {
227
+ const parsed = parseDirection(first);
228
+ if (parsed) {
229
+ direction = parsed;
230
+ parts.shift();
231
+ }
232
+ }
233
+ else if (['ci', 'el', 'cl', 'fa', 'at'].includes(first.slice(0, 2)) ||
234
+ NUMBER_START.includes(first[0])) {
235
+ // A shape, a size or a position comes before the stops.
236
+ checkRadial(first);
237
+ parts.shift();
238
+ }
239
+ else {
240
+ checkRadial('');
241
+ }
242
+ const pending = [];
243
+ for (const part of parts) {
244
+ const words = splitOutside(part, ' ');
245
+ const positions = [];
246
+ while (words.length > 1 &&
247
+ NUMBER_START.includes(words[words.length - 1][0])) {
248
+ positions.unshift(parsePosition(words.pop()));
249
+ }
250
+ if (words.length !== 1 ||
251
+ positions.length > 2 ||
252
+ NUMBER_START.includes(words[0][0])) {
253
+ refuse(`"${part}" is not a color stop`);
254
+ }
255
+ for (const offset of positions.length ? positions : [null]) {
256
+ pending.push({ color: words[0], offset });
257
+ }
258
+ }
259
+ return { type, ...direction, stops: settleStops(pending) };
260
+ }
261
+ /**
262
+ * React Native's object form of a gradient, as the CSS function it stands for.
263
+ *
264
+ * @param value `{type, direction?, colorStops}` or `{type, shape, size?, position?, colorStops}`.
265
+ *
266
+ * @returns The function, for parseString.
267
+ */
268
+ function objectToString(value) {
269
+ if (!Array.isArray(value.colorStops)) {
270
+ refuse('a gradient needs `colorStops`');
271
+ }
272
+ const position = value.position;
273
+ const centered = typeof position === 'object' &&
274
+ position !== null &&
275
+ Object.values(position).every(side => side === '50%');
276
+ const before = value.type === 'radial-gradient'
277
+ ? [
278
+ value.shape,
279
+ value.size,
280
+ position === undefined ? '' : `at ${centered ? 'center' : position}`,
281
+ ].join(' ')
282
+ : (value.direction ?? '');
283
+ const stops = value.colorStops.map(stop => {
284
+ if (typeof stop?.color !== 'string') {
285
+ refuse('each stop needs a `color` string');
286
+ }
287
+ return [stop.color].concat((stop.positions ?? [])).join(' ');
288
+ });
289
+ return `${value.type}(${[before, ...stops].join(',')})`;
290
+ }
291
+ /**
292
+ * Reads a `backgroundImage` style.
293
+ *
294
+ * The engine draws one gradient of two to four stops behind a View: linear at any angle or to a side or
295
+ * corner, or a radial circle from the centre to the farthest corner.
296
+ *
297
+ * @param value A CSS `linear-gradient()` or `radial-gradient()` string, or React Native's array of one
298
+ * gradient object.
299
+ *
300
+ * @returns The gradient, or the problem with the value.
301
+ */
302
+ export function parseBackgroundImage(value) {
303
+ try {
304
+ if (typeof value === 'string') {
305
+ return { gradient: parseString(value) };
306
+ }
307
+ const layers = Array.isArray(value) ? value : [value];
308
+ if (layers.length !== 1) {
309
+ refuse('a View takes one gradient');
310
+ }
311
+ if (typeof layers[0] !== 'object' || layers[0] === null) {
312
+ refuse('expected a gradient string, or an array of one object');
313
+ }
314
+ return { gradient: parseString(objectToString(layers[0])) };
315
+ }
316
+ catch (problem) {
317
+ if (typeof problem !== 'string')
318
+ throw problem;
319
+ return { problem };
320
+ }
321
+ }
@@ -13,7 +13,6 @@
13
13
  * See the License for the specific language governing permissions and
14
14
  * limitations under the License.
15
15
  */
16
-
17
16
  // Host components. Each is the string tag the reconciler passes to NativeUI.createNode(), which
18
17
  // maps it onto an ERNodeType. JSX `<View/>` → createElement('View', ...) → createInstance('View').
19
18
  export const View = 'View';
@@ -21,7 +20,7 @@ export const Text = 'Text';
21
20
  export const Image = 'Image';
22
21
  export const ScrollView = 'ScrollView';
23
22
  // FlatList is NOT a host tag — it is a component that renders a <ScrollView> with `data` mapped
24
- // through `renderItem` (see FlatList.js). ER_NODE_FLAT_LIST exists in the engine but is byte-for-byte
23
+ // through `renderItem` (see FlatList.mts). ER_NODE_FLAT_LIST exists in the engine but is byte-for-byte
25
24
  // a ScrollView, so both flows emit the ScrollView node instead.
26
25
  export const Pressable = 'Pressable';
27
26
  export const TextInput = 'TextInput';
@@ -29,7 +28,6 @@ export const Switch = 'Switch';
29
28
  export const ActivityIndicator = 'ActivityIndicator';
30
29
  export const Modal = 'Modal';
31
30
  export const Dial = 'Dial';
32
-
33
31
  // SVG surface. <Svg> is the only host node (→ ER_NODE_VECTOR); the shape tags below are descriptive
34
32
  // children that the host config flattens into the Svg node's op-tape (they are never mounted on their
35
33
  // own — like raw text inside <Text>). Use them only inside an <Svg>.
@@ -13,59 +13,49 @@
13
13
  * See the License for the specific language governing permissions and
14
14
  * limitations under the License.
15
15
  */
16
-
17
16
  // Imperative escape hatch for high-frequency interactive updates.
18
17
  //
19
18
  // Going through React on every pointer move is too slow on some devices — the
20
19
  // reconcile + flatten dominate. For continuous gestures (e.g., dragging a dial), grab a node handle via
21
20
  // a ref and push updates directly here: it skips React entirely and, for vectors, skips the d-string
22
21
  // parser too. Commit back to React state when the gesture ends so the declarative tree re-syncs.
23
- import {NativeUI} from '../native-ui.js';
24
- import {
25
- shapesToVector,
26
- warnVectorCaps,
27
- encodeVectorGradients,
28
- } from './svg-ops.js';
29
-
22
+ import { NativeUI } from '../native-ui.mjs';
23
+ import { shapesToVector, warnVectorCaps, encodeVectorGradients, } from './svg-ops.mjs';
30
24
  /**
31
25
  * Imperatively sets an <Svg> node's geometry from primitive shape descriptors (see shapesToVector).
32
- * @param {number} handle The node handle from a ref on an <Svg/>.
33
- * @param {Array} shapes Flat array of shape descriptors ({arc}/{circle}/{line}/{rect}/{path} + paint).
34
- * @param {Array} [dirtyRect] Optional node-local [x, y, w, h] bounding the change; when given, only that
35
- * region is repainted and flushed (a big win for small updates on a large
36
- * vector node). Omit to repaint the whole node box.
26
+ * `handle` is the node handle from a ref on an <Svg/>. `shapes` is a flat array of shape descriptors
27
+ * ({arc}/{circle}/{line}/{rect}/{path} + paint). `dirtyRect` is an optional node-local [x, y, w, h]
28
+ * bounding the change; when given, only that region is repainted and flushed (a big win for small updates
29
+ * on a large vector node). Omit it to repaint the whole node box.
37
30
  */
38
31
  export function updateVector(handle, shapes, dirtyRect) {
39
- if (handle == null) return;
40
- const {ops, paints, gradients} = shapesToVector(shapes);
41
- warnVectorCaps(
42
- ops.length,
43
- paints.length,
44
- NativeUI.maxVectorOps,
45
- NativeUI.maxVectorPaints,
46
- gradients.length,
47
- NativeUI.maxVectorGrads,
48
- );
49
- NativeUI.setVectorOps(
50
- handle,
51
- ops,
52
- paints,
53
- gradients.length ? encodeVectorGradients(gradients) : undefined,
54
- dirtyRect,
55
- );
32
+ if (handle == null)
33
+ return;
34
+ const { ops, paints, gradients } = shapesToVector(shapes);
35
+ warnVectorCaps(ops.length, paints.length, NativeUI.maxVectorOps, NativeUI.maxVectorPaints, gradients.length, NativeUI.maxVectorGrads);
36
+ NativeUI.setVectorOps(handle, ops, paints, gradients.length ? encodeVectorGradients(gradients) : undefined, dirtyRect);
56
37
  }
57
-
58
38
  /**
59
39
  * Imperatively sets a <Text> node's text content WITHOUT disturbing its style (uses a single inherited
60
40
  * span, so color/size/etc. from the node's props are preserved). A later React render reverts cleanly.
61
- * @param {number} handle The node handle from a ref on a <Text/>.
62
- * @param {string} text New text content.
41
+ * `handle` is the node handle from a ref on a <Text/>.
63
42
  */
64
43
  export function updateText(handle, text) {
65
- if (handle == null) return;
66
- NativeUI.setTextSpans(handle, [{text: String(text)}]);
44
+ if (handle == null)
45
+ return;
46
+ NativeUI.setTextSpans(handle, [{ text: String(text) }]);
47
+ }
48
+ /**
49
+ * Scrolls a <ScrollView> and returns where it landed. The offset is clamped to the scroll range, and an
50
+ * axis left out stays where it is, so scrollTo(handle) only reads the position.
51
+ * `handle` is the node handle from a ref on a <ScrollView/>, and `offset` is in pixels. Returns the offset
52
+ * and the largest offset on each axis, or undefined when the handle is not a ScrollView.
53
+ */
54
+ export function scrollTo(handle, offset) {
55
+ if (handle == null)
56
+ return undefined;
57
+ return NativeUI.scrollTo(handle, offset?.x, offset?.y);
67
58
  }
68
-
69
59
  /**
70
60
  * Customizes the on-screen software keyboard's appearance and/or layout. Only effective when the engine was
71
61
  * built with the keyboard enabled (ERUI_ONSCREEN_KEYBOARD=1); a no-op otherwise. The config is a plain
@@ -79,8 +69,7 @@ export function updateText(handle, text) {
79
69
  * Key shapes: { char } types it; { char: ' ', span } a space bar; { label, layer } switches layer;
80
70
  * { label, backspace } / { label, done }; optional `span` (grid columns) and `highlight` (lit on its layer).
81
71
  * Pass nothing/null to restore the default.
82
- * @param {object} [config] Keyboard config, or null for the built-in default.
83
72
  */
84
73
  export function setKeyboardConfig(config) {
85
- NativeUI.setKeyboardConfig(config || null);
74
+ NativeUI.setKeyboardConfig(config || null);
86
75
  }