embedded-react 0.21.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 (99) hide show
  1. package/README.md +2 -2
  2. package/aot/compile.mjs +1 -1
  3. package/aot/compiler/alerts.mjs +604 -0
  4. package/aot/compiler/check.mjs +1 -1
  5. package/aot/compiler/collect.mjs +1 -1
  6. package/aot/compiler/elements/button.mjs +3 -3
  7. package/aot/compiler/elements/image-background.mjs +1 -1
  8. package/aot/compiler/elements/props.mjs +10 -6
  9. package/aot/compiler/elements/section-list.mjs +1 -1
  10. package/aot/compiler/expressions.mjs +29 -2
  11. package/aot/compiler/handlers.mjs +73 -16
  12. package/aot/compiler/keyboard-dismiss.mjs +99 -0
  13. package/aot/compiler/keyboard.mjs +1 -1
  14. package/aot/compiler/lower.mjs +12 -0
  15. package/aot/compiler/nodes.mjs +17 -9
  16. package/aot/compiler/out.mjs +4 -0
  17. package/aot/compiler/package/codegen.mjs +36 -2
  18. package/aot/compiler/package/format.mjs +5 -3
  19. package/aot/compiler/package/lower.mjs +53 -19
  20. package/aot/compiler/scroll-to.mjs +112 -0
  21. package/aot/compiler/style-text.mjs +2 -2
  22. package/aot/compiler/svg.mjs +6 -3
  23. package/aot/compiler/updaters.mjs +1 -0
  24. package/aot/style-map.mjs +44 -1
  25. package/assets/bake-font.mjs +187 -244
  26. package/assets/bake-image.mjs +47 -71
  27. package/assets/bake-svg.mjs +465 -533
  28. package/assets/build-builtin-font.mjs +14 -27
  29. package/assets/emit-c.mjs +124 -204
  30. package/assets/emit-container.mjs +129 -197
  31. package/assets/emit-pack.mjs +92 -136
  32. package/assets/font-config.mjs +19 -27
  33. package/assets/font-sizes.mjs +432 -507
  34. package/assets/glyph-coverage.mjs +170 -214
  35. package/assets/index.mjs +52 -97
  36. package/assets/rasterize.mjs +173 -194
  37. package/assets/svg-loader.mjs +42 -48
  38. package/build.mjs +84 -101
  39. package/cli.mjs +482 -621
  40. package/compile-bin.mjs +24 -36
  41. package/flash.mjs +297 -401
  42. package/hotreload/dev-device.mjs +229 -270
  43. package/hotreload/pack-app.mjs +118 -159
  44. package/hotreload/pack-split.mjs +144 -200
  45. package/hotreload/package-transfer.mjs +128 -131
  46. package/hotreload/protocol.mjs +118 -118
  47. package/hotreload/uploader.mjs +132 -159
  48. package/hotreload/watch-tree.mjs +56 -65
  49. package/pack-container.mjs +93 -123
  50. package/package.json +19 -16
  51. package/persist-transform.mjs +89 -105
  52. package/qjsc-wasm.mjs +47 -72
  53. package/sim/embedded-react.wasm +0 -0
  54. package/sim/index.html +1 -1
  55. package/sim-server.mjs +260 -354
  56. package/src/embedded-react/Alert.mjs +112 -0
  57. package/src/embedded-react/Animated.mjs +412 -0
  58. package/src/embedded-react/{AppRegistry.js → AppRegistry.mjs} +26 -25
  59. package/src/embedded-react/{Button.js → Button.mjs} +29 -53
  60. package/src/embedded-react/{Dimensions.js → Dimensions.mjs} +12 -17
  61. package/src/embedded-react/Easing.mjs +34 -0
  62. package/src/embedded-react/{FlatList.js → FlatList.mjs} +25 -42
  63. package/src/embedded-react/{ImageBackground.js → ImageBackground.mjs} +11 -22
  64. package/src/embedded-react/Keyboard.mjs +82 -0
  65. package/src/embedded-react/{LayoutAnimation.js → LayoutAnimation.mjs} +17 -28
  66. package/src/embedded-react/PanResponder.mjs +256 -0
  67. package/src/embedded-react/{Platform.js → Platform.mjs} +8 -9
  68. package/src/embedded-react/{Pressable.js → Pressable.mjs} +12 -25
  69. package/src/embedded-react/SectionList.mjs +103 -0
  70. package/src/embedded-react/{StyleSheet.js → StyleSheet.mjs} +16 -20
  71. package/src/embedded-react/{TouchableOpacity.js → TouchableOpacity.mjs} +47 -83
  72. package/src/embedded-react/background-image.mjs +321 -0
  73. package/src/embedded-react/{components.js → components.mjs} +1 -3
  74. package/src/embedded-react/{imperative.js → imperative.mjs} +27 -38
  75. package/src/embedded-react/index.d.ts +155 -2
  76. package/src/embedded-react/index.js +26 -19
  77. package/src/embedded-react/layout-anim-config.mjs +85 -0
  78. package/src/embedded-react/{list-child.js → list-child.mjs} +11 -20
  79. package/src/embedded-react/{named-colors.js → named-colors.mjs} +2 -6
  80. package/src/embedded-react/nativeModule.mjs +371 -0
  81. package/src/embedded-react/split-style.mjs +57 -0
  82. package/src/embedded-react/svg-ops.mjs +1075 -0
  83. package/src/embedded-react/{useHostValue.js → useHostValue.mjs} +2 -4
  84. package/src/embedded-react/{usePersistentState.js → usePersistentState.mjs} +34 -38
  85. package/src/embedded-react/{warn-props.js → warn-props.mjs} +32 -39
  86. package/src/host-config.mjs +512 -0
  87. package/src/{native-ui.js → native-ui.mjs} +1 -8
  88. package/src/props.mjs +341 -0
  89. package/src/{renderer.js → renderer.mjs} +30 -44
  90. package/src/embedded-react/Animated.js +0 -440
  91. package/src/embedded-react/Easing.js +0 -39
  92. package/src/embedded-react/PanResponder.js +0 -330
  93. package/src/embedded-react/SectionList.js +0 -146
  94. package/src/embedded-react/layout-anim-config.js +0 -101
  95. package/src/embedded-react/nativeModule.js +0 -462
  96. package/src/embedded-react/split-style.js +0 -58
  97. package/src/embedded-react/svg-ops.js +0 -1295
  98. package/src/host-config.js +0 -548
  99. 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
  }
@@ -20,7 +20,7 @@
20
20
  //
21
21
  // What is declared here is what the RUNTIME honors. The sources of truth are the bridge's prop and event
22
22
  // tables (`k_prop_names` / `event_type_from_name` in bridges/quickjs/native_ui_bridge.c), the top-level
23
- // prop list (`PASSTHROUGH` in src/props.js), and the SVG compiler (src/embedded-react/svg-ops.js). A prop
23
+ // prop list (`PASSTHROUGH` in src/props.mts), and the SVG compiler (src/embedded-react/svg-ops.mts). A prop
24
24
  // the engine ignores is deliberately absent, so a name that typechecks is a name that reaches the engine.
25
25
  // `npm test` runs a parity test over those tables to keep it that way.
26
26
  //
@@ -75,10 +75,36 @@ export type StyleValue =
75
75
  | number
76
76
  | AnimatedNode
77
77
  | TransformStyle[]
78
+ | BackgroundImageValue[]
78
79
  | ShadowOffset
79
80
  | TransformOrigin
80
81
  | undefined;
81
82
 
83
+ /** A color stop of a gradient. Each position is a percentage such as `'40%'`; two paint the color across a band. */
84
+ export interface GradientColorStop {
85
+ color: string;
86
+ positions?: string[];
87
+ }
88
+
89
+ /**
90
+ * A gradient in React Native's object form. `direction` is an angle (`'45deg'`) or `to` a side or corner
91
+ * (`'to bottom right'`), and defaults to `'to bottom'`. A radial gradient is a circle from the center to the
92
+ * farthest corner.
93
+ */
94
+ export type BackgroundImageValue =
95
+ | {
96
+ type: 'linear-gradient';
97
+ direction?: string;
98
+ colorStops: GradientColorStop[];
99
+ }
100
+ | {
101
+ type: 'radial-gradient';
102
+ shape: 'circle';
103
+ size?: 'farthest-corner';
104
+ position?: 'center';
105
+ colorStops: GradientColorStop[];
106
+ };
107
+
82
108
  /** A single style object. Properties mirror the React Native subset the engine supports. */
83
109
  export interface ViewStyle {
84
110
  [key: string]: StyleValue;
@@ -158,6 +184,12 @@ export interface ViewStyle {
158
184
 
159
185
  // Paint.
160
186
  backgroundColor?: string | AnimatedNode;
187
+ /**
188
+ * One gradient of two to four stops behind a View, ScrollView or Pressable: a CSS `linear-gradient()` or
189
+ * `radial-gradient(circle, ...)` string, or an array of one gradient object. Firmware built without
190
+ * `ERUI_GRADIENT` paints `backgroundColor` instead.
191
+ */
192
+ backgroundImage?: string | BackgroundImageValue[];
161
193
  opacity?: number | AnimatedNode;
162
194
 
163
195
  // Border.
@@ -805,6 +837,72 @@ export const Dimensions: {
805
837
  /** The panel's size. It is fixed while the app runs. */
806
838
  export function useWindowDimensions(): ScaledSize;
807
839
 
840
+ // --- Alert -----------------------------------------------------------------
841
+ export interface AlertButton {
842
+ text?: string;
843
+ onPress?: () => void;
844
+ /** 'destructive' draws the label in red; 'cancel' looks like 'default'. */
845
+ style?: 'default' | 'cancel' | 'destructive';
846
+ }
847
+
848
+ export interface AlertOptions {
849
+ /** Lets a tap outside the dialog close it. Off by default. */
850
+ cancelable?: boolean;
851
+ /** Called when a tap outside closes a cancelable alert. */
852
+ onDismiss?: () => void;
853
+ }
854
+
855
+ export const Alert: {
856
+ /**
857
+ * Shows a stock dialog over the app. With no buttons it gets a single "OK". A second alert waits
858
+ * until the first is closed; in Flow B it replaces the first.
859
+ */
860
+ alert(
861
+ title: string,
862
+ message?: string,
863
+ buttons?: AlertButton[],
864
+ options?: AlertOptions,
865
+ ): void;
866
+ };
867
+
868
+ // --- Keyboard --------------------------------------------------------------
869
+ export type KeyboardEventName =
870
+ | 'keyboardWillShow'
871
+ | 'keyboardDidShow'
872
+ | 'keyboardWillHide'
873
+ | 'keyboardDidHide';
874
+
875
+ /** The strip of the screen the on-screen keyboard covers, in pixels. */
876
+ export interface KeyboardMetrics {
877
+ screenX: number;
878
+ screenY: number;
879
+ width: number;
880
+ height: number;
881
+ }
882
+
883
+ export interface KeyboardEvent {
884
+ /** Where the keyboard ends up: its strip when it shows, the same strip just below the screen when it hides. */
885
+ endCoordinates: KeyboardMetrics;
886
+ }
887
+
888
+ /**
889
+ * The on-screen keyboard, which shows while a `<TextInput>` has the focus. A build without it
890
+ * (ERUI_ONSCREEN_KEYBOARD=0) fires no events and is never visible; `dismiss()` still takes the focus away.
891
+ */
892
+ export const Keyboard: {
893
+ /** Nothing animates, so each "will" event fires just before its "did". */
894
+ addListener(
895
+ eventName: KeyboardEventName,
896
+ listener: (event: KeyboardEvent) => void,
897
+ ): {remove(): void};
898
+ removeAllListeners(eventName: KeyboardEventName): void;
899
+ /** Takes the focus from the focused `<TextInput>`, which hides the keyboard. */
900
+ dismiss(): void;
901
+ isVisible(): boolean;
902
+ /** The keyboard's strip, or undefined while it is hidden. */
903
+ metrics(): KeyboardMetrics | undefined;
904
+ };
905
+
808
906
  // --- AppRegistry -----------------------------------------------------------
809
907
  export const AppRegistry: {
810
908
  registerComponent(
@@ -1012,7 +1110,44 @@ export type NativeMock<T> =
1012
1110
  export const Easing: {readonly [K in EasingName]: K} & {
1013
1111
  bezier(x1: number, y1: number, x2: number, y2: number): BezierEasing;
1014
1112
  };
1015
- export const LayoutAnimation: Record<string, unknown>;
1113
+
1114
+ // --- LayoutAnimation -------------------------------------------------------
1115
+
1116
+ /** One phase of a layout animation. */
1117
+ export interface LayoutAnimationPhase {
1118
+ type?: string;
1119
+ property?: string;
1120
+ springDamping?: number;
1121
+ }
1122
+
1123
+ /** A layout animation, in React Native's shape. The engine tweens position; `update.type` picks the curve. */
1124
+ export interface LayoutAnimationConfig {
1125
+ /** Default 300. */
1126
+ duration?: number;
1127
+ type?: string;
1128
+ create?: LayoutAnimationPhase;
1129
+ update?: LayoutAnimationPhase;
1130
+ delete?: LayoutAnimationPhase;
1131
+ }
1132
+
1133
+ export const LayoutAnimation: {
1134
+ /** Animates the layout changes of the next commit. Call it right before the state update that moves things. */
1135
+ configureNext(config?: LayoutAnimationConfig | null, done?: () => void): void;
1136
+ create(
1137
+ duration: number,
1138
+ type?: string,
1139
+ creationProp?: string,
1140
+ ): LayoutAnimationConfig;
1141
+ Types: Record<
1142
+ 'spring' | 'linear' | 'easeInEaseOut' | 'easeIn' | 'easeOut' | 'keyboard',
1143
+ string
1144
+ >;
1145
+ Properties: Record<'opacity' | 'scaleX' | 'scaleY' | 'scaleXY', string>;
1146
+ Presets: Record<'easeInEaseOut' | 'linear' | 'spring', LayoutAnimationConfig>;
1147
+ easeInEaseOut(done?: () => void): void;
1148
+ linear(done?: () => void): void;
1149
+ spring(done?: () => void): void;
1150
+ };
1016
1151
 
1017
1152
  // --- PanResponder ----------------------------------------------------------
1018
1153
 
@@ -1159,6 +1294,24 @@ export function updateText(
1159
1294
  text: string | number,
1160
1295
  ): void;
1161
1296
 
1297
+ /** Where a `<ScrollView>` is scrolled to, and the largest offset it accepts on each axis. */
1298
+ export interface ScrollPosition {
1299
+ x: number;
1300
+ y: number;
1301
+ maxX: number;
1302
+ maxY: number;
1303
+ }
1304
+
1305
+ /**
1306
+ * Scrolls a `<ScrollView>` and returns where it landed, or `undefined` when the handle is not a
1307
+ * ScrollView. The offset is clamped to the scroll range, and an axis left out stays where it is, so
1308
+ * `scrollTo(handle)` only reads the position. The range is as of the last render.
1309
+ */
1310
+ export function scrollTo(
1311
+ handle: NodeHandle | null | undefined,
1312
+ offset?: {x?: number; y?: number},
1313
+ ): ScrollPosition | undefined;
1314
+
1162
1315
  /** One key in a `setKeyboardConfig` layer. `char` types it; `layer` switches layer; `backspace`/`done` act. */
1163
1316
  export interface KeyboardKey {
1164
1317
  char?: string;