embedded-react 0.11.1 → 0.13.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/README.md +162 -4
- package/aot/compile.mjs +1270 -73
- package/aot/style-map.mjs +13 -5
- package/assets/bake-font.mjs +104 -12
- package/assets/bake-svg.mjs +11 -1
- package/assets/build-builtin-font.mjs +6 -12
- package/assets/emit-c.mjs +10 -2
- package/assets/font-config.mjs +49 -0
- package/assets/font-sizes.mjs +652 -0
- package/assets/glyph-coverage.mjs +281 -0
- package/assets/index.mjs +29 -5
- package/build.mjs +11 -21
- package/cli.mjs +13 -1
- package/compile-bin.mjs +71 -0
- package/hotreload/pack-app.mjs +8 -21
- package/hotreload/pack-split.mjs +12 -27
- package/pack-container.mjs +10 -47
- package/package.json +2 -1
- package/sim/embedded-react.wasm +0 -0
- package/sim/index.html +32 -3
- package/sim-server.mjs +33 -27
- package/src/embedded-react/Animated.js +23 -9
- package/src/embedded-react/Button.js +98 -0
- package/src/embedded-react/FlatList.js +88 -0
- package/src/embedded-react/ImageBackground.js +67 -0
- package/src/embedded-react/PanResponder.js +326 -0
- package/src/embedded-react/SectionList.js +148 -0
- package/src/embedded-react/TouchableOpacity.js +152 -0
- package/src/embedded-react/components.js +4 -3
- package/src/embedded-react/index.d.ts +868 -59
- package/src/embedded-react/index.js +7 -2
- package/src/embedded-react/list-child.js +54 -0
- package/src/embedded-react/svg-ops.js +220 -72
- package/src/embedded-react/warn-props.js +80 -0
- package/src/host-config.js +98 -3
- package/src/props.js +47 -0
package/README.md
CHANGED
|
@@ -37,6 +37,32 @@ AppRegistry.registerComponent('demo', () => App);
|
|
|
37
37
|
`embedded-react` resolves as a Node **package self-reference** (`package.json` `name` + `exports`),
|
|
38
38
|
so esbuild and Vitest find it with no aliases.
|
|
39
39
|
|
|
40
|
+
`<FlatList>` renders, but it is a thin `<ScrollView>` alias — no virtualization, every row mounts and
|
|
41
|
+
stays mounted, and only `data` / `renderItem` / `keyExtractor` / `style` are honored. See [`FlatList` is
|
|
42
|
+
a `ScrollView`
|
|
43
|
+
alias](https://github.com/TheMasterCoder007/embedded-react#flatlist-is-a-scrollview-alias) for the node
|
|
44
|
+
budget it costs and what to do with a long list.
|
|
45
|
+
|
|
46
|
+
`<Button>`, `<ImageBackground>` and `<SectionList>` are JavaScript wrappers over the primitives, the
|
|
47
|
+
way RN implements them — a styled `<Pressable>` + `<Text>`, a `<View>` with an absolutely-filled
|
|
48
|
+
`<Image>` behind its children, and a `<ScrollView>` whose sections lay out as flat siblings. They add
|
|
49
|
+
no engine node, they are **Flow A only** (the AOT names them and tells you the tree to write instead),
|
|
50
|
+
and `<SectionList>` inherits every `<FlatList>` caveat plus a header and footer per section. See
|
|
51
|
+
[`Button`, `ImageBackground` and `SectionList` are JSX, not
|
|
52
|
+
nodes](https://github.com/TheMasterCoder007/embedded-react#button-imagebackground-and-sectionlist-are-jsx-not-nodes).
|
|
53
|
+
|
|
54
|
+
`<TouchableOpacity>` is a wrapper too, but a cheaper one: it is a `<Pressable>` whose opacity is bound to
|
|
55
|
+
a press animation, so it costs no extra node and it compiles in **both flows**. The dim runs on the
|
|
56
|
+
native driver — no JS per frame — and every `<Pressable>` prop works on it unchanged. See
|
|
57
|
+
[`<TouchableOpacity>` dims on the native
|
|
58
|
+
driver](https://github.com/TheMasterCoder007/embedded-react#touchableopacity-dims-on-the-native-driver).
|
|
59
|
+
|
|
60
|
+
RN modules that wrap an operating system — `StatusBar`, `SafeAreaView`, `AppState`, `Appearance`,
|
|
61
|
+
`Linking`, `AccessibilityInfo` — are **intentionally absent**; a microcontroller has no OS for them to
|
|
62
|
+
wrap. See [Intentionally absent React Native
|
|
63
|
+
APIs](https://github.com/TheMasterCoder007/embedded-react#intentionally-absent-react-native-apis) for
|
|
64
|
+
the full list and what to use instead.
|
|
65
|
+
|
|
40
66
|
## Simulate — `npx embedded-react dev`
|
|
41
67
|
|
|
42
68
|
Run your app in a browser with hot reload — no native toolchain, no repo clone. The engine is compiled to
|
|
@@ -67,12 +93,13 @@ npx embedded-react export --out sim-export # then: npx serve sim-export (or d
|
|
|
67
93
|
```
|
|
68
94
|
src/
|
|
69
95
|
embedded-react/ the public package surface (what apps import)
|
|
70
|
-
index.js barrel: components, StyleSheet, Platform, AppRegistry, Animated, Easing
|
|
96
|
+
index.js barrel: components, StyleSheet, Platform, AppRegistry, Animated, PanResponder, Easing
|
|
71
97
|
components.js host component tags (View, Text, … → ERNodeType)
|
|
72
98
|
StyleSheet.js create() / flatten()
|
|
73
99
|
Platform.js { OS: 'embedded', select }
|
|
74
100
|
AppRegistry.js registerComponent(...) → mounts into a screen-sized root
|
|
75
101
|
Animated.js Value / timing / spring / decay / View|Text|Image / interpolate
|
|
102
|
+
PanResponder.js create(config) → panHandlers: drag/swipe/fling over the responder system
|
|
76
103
|
Easing.js easing tokens (+ bezier) → engine curves
|
|
77
104
|
split-style.js pure: split style into static props + animated bindings
|
|
78
105
|
__tests__/ co-located UNIT tests for the pure surface
|
|
@@ -94,6 +121,7 @@ assets/ build-time asset bakers (pure JS, no native deps) —
|
|
|
94
121
|
build.mjs esbuild a demo's index.jsx → dist/app.bundle.js + bake its imported assets
|
|
95
122
|
pack-container.mjs bundle + bytecode-compile + bake → dist/app.erpkg config container (npm run pack)
|
|
96
123
|
assets/emit-container.mjs ERCF container writer (sections + QuickJS version stamp + CRC32)
|
|
124
|
+
compile-bin.mjs finds er-bridge-quickjs-compile (shared with the parity harness)
|
|
97
125
|
vitest.config.js unit test config
|
|
98
126
|
```
|
|
99
127
|
|
|
@@ -108,6 +136,94 @@ interpolation like `Hi {name}`, or nested `<Text>` runs) becomes the node's `tex
|
|
|
108
136
|
`Animated`, `Easing`, and the web timer globals (`setTimeout` / `setInterval`) are all available;
|
|
109
137
|
`useEffect` flushes via the host pump.
|
|
110
138
|
|
|
139
|
+
### Hiding a subtree (`display: 'none'`) — page caching
|
|
140
|
+
|
|
141
|
+
```jsx
|
|
142
|
+
<View style={{display: page === 'home' ? 'flex' : 'none'}}><Home /></View>
|
|
143
|
+
<View style={{display: page === 'settings' ? 'flex' : 'none'}}><Settings /></View>
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
A hidden subtree drops out of layout, rendering, and hit-testing, but stays **mounted** — its React
|
|
147
|
+
state and effects survive, and the native nodes behind it keep their props. That is the difference
|
|
148
|
+
from the conditional render (`{page === 'home' && <Home/>}`) it replaces: a conditional unmounts the
|
|
149
|
+
page and rebuilds every node in interpreted QuickJS on the way back, which is the dominant cost of a
|
|
150
|
+
page change. Hiding costs a repaint, and a hidden page costs nothing per frame even while React keeps
|
|
151
|
+
rendering into it.
|
|
152
|
+
|
|
153
|
+
`visible={false}` is the same switch under the other spelling, with an explicit `style.display`
|
|
154
|
+
winning over it (`<Modal visible>` is unaffected — that is the Modal's own show/hide prop). Both work
|
|
155
|
+
in Flow B too, where `display` can be static or state-driven — `display: page === 'home' ? 'flex' : 'none'`
|
|
156
|
+
compiles, but a state-driven one has to be a string literal or a ternary of them, whereas `visible` takes
|
|
157
|
+
any boolean expression. Either spelling lowers to a `p.display` write in `app_update`, so hiding costs no
|
|
158
|
+
node churn there either. The one gap is `visible` on an `<Svg>`, which the AOT rejects outright: wrap it
|
|
159
|
+
(`<View visible={…}><Svg …/></View>`) and the whole subtree goes with the View.
|
|
160
|
+
The trade is memory: a cached page holds its nodes for the life of the app, so cache
|
|
161
|
+
the pages you flip between, not every page.
|
|
162
|
+
|
|
163
|
+
### Gestures — `PanResponder`
|
|
164
|
+
|
|
165
|
+
The raw touch events already carry the travel and the speed (`e.dx`/`e.dy`, `e.vx`/`e.vy` — see below),
|
|
166
|
+
which is enough for a one-off flick. A real drag wants more: an anchor that starts at zero, however, the
|
|
167
|
+
gesture was won, ownership against a scrolling ancestor, and a teardown hook for when the gesture is
|
|
168
|
+
taken away. `PanResponder` is that, in the RN shape (and it compiles in Flow B as well as Flow A):
|
|
169
|
+
|
|
170
|
+
```jsx
|
|
171
|
+
const pan = useRef(
|
|
172
|
+
PanResponder.create({
|
|
173
|
+
onStartShouldSetPanResponder: () => true,
|
|
174
|
+
onPanResponderMove: (e, g) => setX(g.dx),
|
|
175
|
+
onPanResponderRelease: (e, g) => (g.vx > 0.5 ? next() : settle()),
|
|
176
|
+
}),
|
|
177
|
+
).current;
|
|
178
|
+
|
|
179
|
+
<View style={styles.overlay} {...pan.panHandlers} />;
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Create it **once** per component and keep it in a ref — the handlers close over one gesture state, so
|
|
183
|
+
re-creating it per render throws the drag away. `gestureState` carries `x0`/`y0` (the grant point),
|
|
184
|
+
`dx`/`dy` (travel since the grant), `vx`/`vy` (px per ms), `moveX`/`moveY`, `numberActiveTouches` and
|
|
185
|
+
`stateID`. Returning `true` from `onMoveShouldSetPanResponder` claims the gesture mid-pan and re-anchors
|
|
186
|
+
`dx`/`dy` at that point, so a slop threshold never shows up as a jump. With neither should-set callback
|
|
187
|
+
supplied nothing is ever granted — same as RN.
|
|
188
|
+
|
|
189
|
+
`panHandlers` are the RN **responder props** — should-set queries plus `onResponderGrant`/`Move`/
|
|
190
|
+
`Release`/`Terminate` — wired straight into the engine's C responder system, so claiming is real
|
|
191
|
+
*negotiation*, not just listening:
|
|
192
|
+
|
|
193
|
+
- **A granted pan OWNS the gesture.** A `ScrollView` ancestor will not auto-scroll under it, and a
|
|
194
|
+
`onMoveShouldSetPanResponder` claim takes the gesture *back* from a scroller that already started
|
|
195
|
+
(which then stops dead — no coasting).
|
|
196
|
+
- **Negotiation covers the subtree.** The engine asks every node on the hit chain — capture phase
|
|
197
|
+
root→leaf first (the `*Capture` config keys), then bubble leaf→root — so one responder on a wrapper
|
|
198
|
+
claims its children's touches, and an outer responder can pre-empt an inner one.
|
|
199
|
+
- **Losing and defending are callbacks.** A refused claim lands on `onPanResponderReject` (and is
|
|
200
|
+
re-asked on every later move while the predicate keeps returning true); a challenger asking for the
|
|
201
|
+
gesture hits the holder's `onPanResponderTerminationRequest` — return `false` to keep it (absent =
|
|
202
|
+
yield, as in RN).
|
|
203
|
+
- **`onPanResponderTerminate` is the undo hook.** It fires when the host cancels the touch sequence,
|
|
204
|
+
when a fresh touch-down arrives on a finger whose previous sequence never ended, and when the
|
|
205
|
+
responder yields to a challenger.
|
|
206
|
+
- **Single gesture.** The engine events carry no finger id, so extra fingers fold into ONE gesture:
|
|
207
|
+
`numberActiveTouches` counts them and the last to lift releases — both true in either flow. Flow A
|
|
208
|
+
additionally reports each join and leave through `onPanResponderStart`/`End`; Flow B has no
|
|
209
|
+
equivalent (next bullet).
|
|
210
|
+
- **Flow B compiles it too.** The AOT recognises `useRef(PanResponder.create({…})).current` and the
|
|
211
|
+
`{...pan.panHandlers}` spread as a whole and lowers them onto the same C responder system — the
|
|
212
|
+
should-set predicates become `er_responder_query_set` callbacks and the rest become responder event
|
|
213
|
+
handlers, with `g.dx`/`g.vx` reading the engine's own payload. No JS state machine is copied into the
|
|
214
|
+
generated C. Only `onPanResponderStart`/`End` — the two that fold EXTRA fingers into one gesture —
|
|
215
|
+
are Flow A only, and the AOT fails the build by name rather than dropping them. The watch-face demo's
|
|
216
|
+
swipe pager is the worked example: one source, both flows.
|
|
217
|
+
|
|
218
|
+
As promised above: the raw touch events carry the same fields the responder ones do — `e.dx`/`e.dy` from
|
|
219
|
+
touch-down and `e.vx`/`e.vy` in px per ms — so `onTouchEnd={e => e.vx > 0.4 && next()}` needs no
|
|
220
|
+
recognizer at all, in either flow.
|
|
221
|
+
|
|
222
|
+
The low-level responder props (`onStartShouldSetResponder`, `onResponderGrant`, …) are themselves
|
|
223
|
+
public on every component for gestures that don't fit the pan shape. Only RN's Android-specific
|
|
224
|
+
`onShouldBlockNativeResponder` is unsupported — holding the responder already blocks the native one
|
|
225
|
+
(the built-in adjustable-Arc drag deliberately still wins). Passing it, or a typo, warns.
|
|
226
|
+
|
|
111
227
|
## Build
|
|
112
228
|
|
|
113
229
|
```
|
|
@@ -151,15 +267,26 @@ file's basename.
|
|
|
151
267
|
RGB565 images through its opaque copy fast path (no per-pixel blending).
|
|
152
268
|
- **Fonts:** TTF/OTF → pre-rasterized `BitmapFont` glyphs (`bake-font.mjs`, via `opentype.js` + a
|
|
153
269
|
pure-JS rasterizer). The engine has no runtime rasterizer, so the baker rasterizes **exactly the
|
|
154
|
-
|
|
155
|
-
|
|
270
|
+
`fontSize` values the app uses**. Discovery folds constants, so a token-driven type scale bakes
|
|
271
|
+
what it means — `const TYPE = {body: 14, title: 22}` read as `fontSize: TYPE.title`, including a
|
|
272
|
+
scale handed to a component as a prop, and both arms of a `screen.width` ternary. A size that only
|
|
273
|
+
exists at runtime can't be seen; the build **warns** and names the expression, because at runtime
|
|
274
|
+
it silently snaps to the nearest baked size. Sizes the bake missed are warned about the same way,
|
|
275
|
+
against your fonts or against the built-in one — pin them in `assets.config.js` if you want a
|
|
276
|
+
different set. Only the glyphs you ask for are baked: printable ASCII, plus a named symbol set and
|
|
277
|
+
any per-app characters you add.
|
|
156
278
|
|
|
157
279
|
Optional per-demo overrides live in `demos/<demo>/assets.config.js`:
|
|
158
280
|
|
|
159
281
|
```js
|
|
160
282
|
export default {
|
|
161
283
|
fonts: {
|
|
162
|
-
Inter: {
|
|
284
|
+
Inter: {
|
|
285
|
+
sizes: [14, 18, 24], // bpp 1|2|4|8 (4 default)
|
|
286
|
+
bpp: 4,
|
|
287
|
+
glyphs: 'common', // 'ascii'|'minimal'|'common'|'greek'|'common-greek'|[codepoints]
|
|
288
|
+
extraGlyphs: '⌘⏻№', // this app's own characters, on top of `glyphs`
|
|
289
|
+
},
|
|
163
290
|
},
|
|
164
291
|
images: {
|
|
165
292
|
bg: { format: 'rgb565' }, // 16-bit bake for opaque art; default is 'argb8888'
|
|
@@ -167,6 +294,21 @@ export default {
|
|
|
167
294
|
};
|
|
168
295
|
```
|
|
169
296
|
|
|
297
|
+
`extraGlyphs` takes the characters themselves or their codepoints (`[0x2318, '⏻']`) — the named sets
|
|
298
|
+
can't anticipate every UI. Every bake path checks the app's text against what it baked and **warns
|
|
299
|
+
about characters that have no glyph**, since the engine silently substitutes `?` for them on the
|
|
300
|
+
device and nothing else tells you:
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
embedded-react: 1 character(s) in the app's text have no baked glyph and will render as '?':
|
|
304
|
+
U+2318 '⌘' missing from Inter in "press ⌘S to save"
|
|
305
|
+
fix: assets.config.js → fonts: {Inter: {extraGlyphs: "⌘"}}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
The check reads string literals (and, for Flow B's unbundled JSX, element text), so text assembled
|
|
309
|
+
at runtime is out of its reach. It also says when the .ttf itself has no such glyph — then no config
|
|
310
|
+
change helps and the font is the thing to change.
|
|
311
|
+
|
|
170
312
|
The engine's **built-in default font** (`engine/font/font_data.c`, the Inter fallback used by any
|
|
171
313
|
text without a custom `fontFamily`) is generated by the same baker — regenerate it with
|
|
172
314
|
`npm run build:builtin-font` (then re-run the engine text tests, as glyph metrics shift slightly).
|
|
@@ -256,6 +398,15 @@ anything that exercises the reconciler → engine pipeline → a `test/runtime/*
|
|
|
256
398
|
tweens every node whose computed rect moved on the next commit (in C — no per-frame JS). `Presets`
|
|
257
399
|
/ `create` / `Types` / `Properties` and the `easeInEaseOut`/`linear`/`spring` shorthands. Covered
|
|
258
400
|
by `layout-animation` unit + `layout-anim.runtime.test.jsx`.
|
|
401
|
+
- ✅ **`PanResponder` + the gesture responder system.** The full RN config minus only the
|
|
402
|
+
Android-specific `onShouldBlockNativeResponder`: should-set predicates (with `*Capture` variants),
|
|
403
|
+
grant / move / release / terminate / reject / termination-request, `onPanResponderStart`/`End` for
|
|
404
|
+
extra fingers, and a `gestureState` (`x0`/`y0`, `dx`/`dy`, `vx`/`vy`, `numberActiveTouches`) — wired
|
|
405
|
+
to the ENGINE's responder negotiation, so a granted pan blocks a ScrollView's auto-scroll and can
|
|
406
|
+
take a started scroll over. The low-level responder props are public on every component, and **Flow B
|
|
407
|
+
compiles the same config** — the AOT lowers it onto that C responder system, minus only
|
|
408
|
+
`onPanResponderStart`/`End`. Covered by `pan-responder` unit + `pan-responder.runtime.test.jsx` + the
|
|
409
|
+
AOT's `compile`/`cc-compile` PanResponder cases + the engine's `test_input` responder cases.
|
|
259
410
|
- ✅ **Interpolate `extrapolate`.** `interpolate({ inputRange, outputRange, extrapolate })` supports
|
|
260
411
|
`'extend'` (default) / `'clamp'` / `'identity'`, with per-end `extrapolateLeft`/`extrapolateRight`
|
|
261
412
|
overrides. Math is engine-tested (`test_interpolate`); the bridge path by
|
|
@@ -268,6 +419,13 @@ anything that exercises the reconciler → engine pipeline → a `test/runtime/*
|
|
|
268
419
|
it's just `useState`, so the same app code runs everywhere. `usePersistentState` is the underlying
|
|
269
420
|
helper, also exported for explicit use. See
|
|
270
421
|
[tools/simulator in the repo](https://github.com/TheMasterCoder007/embedded-react/blob/master/tools/simulator/README.md).
|
|
422
|
+
- ✅ **`<Dial>` — the native arc widget.** Dials, gauges and progress rings as ONE engine node
|
|
423
|
+
(`ER_NODE_ARC`) instead of a re-tessellated `<Svg>`: track + value indicator, optional backing band,
|
|
424
|
+
segment gaps, round caps, a circle / image / child-anchored knob, solid / conic / radial indicator paint.
|
|
425
|
+
`value` accepts an `Animated.Value` (bound natively — no JS per frame; each tick repaints only the swept
|
|
426
|
+
sliver), and `adjustable` gives built-in drag-to-set with the quantized value delivered to `onChange(v)`.
|
|
427
|
+
`<Switch onValueChange>` now also fires in Flow A (it was AOT-only). Covered by `dial.runtime.test.jsx`
|
|
428
|
+
and the engine's `test_arc`.
|
|
271
429
|
- ✅ **`npx embedded-react dev`** — the WASM simulator runs your app in a browser with hot reload, from your
|
|
272
430
|
own project directory, with the engine `.wasm` shipped prebuilt (no Emscripten for consumers). See above.
|
|
273
431
|
- ✅ **`npm create embedded-react@latest my-app`** — scaffolds a fresh standalone project (a styled card with a
|