@symbiote-native/system-ui 3.0.2 → 3.0.3

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 (2) hide show
  1. package/README.md +34 -24
  2. package/package.json +15 -15
package/README.md CHANGED
@@ -1,13 +1,13 @@
1
1
  # @symbiote-native/system-ui
2
2
 
3
3
  A wrapper package for [SymbioteNative](../../README.md) that makes
4
- [`expo-system-ui`](https://github.com/expo/expo/tree/main/packages/expo-system-ui)
5
- — setting and reading the root view's background color — usable from **every** adapter,
4
+ [`expo-system-ui`](https://github.com/expo/expo/tree/main/packages/expo-system-ui):
5
+ setting and reading the root view's background color - usable from **every** adapter,
6
6
  React, Vue, Svelte, Solid, and Angular, not just React. Like
7
7
  [`@symbiote-native/device`](../device) and [`@symbiote-native/local-auth`](../local-auth) and
8
8
  unlike this repo's stateful Expo wrapper ([`@symbiote-native/sensors`](../sensors), an
9
9
  `EventEmitter` + live-subscription surface), both exports here are one-shot async calls with no
10
- per-instance state, so there is no hook/composable/service to wrap — the React, Vue, Svelte, and
10
+ per-instance state, so there is no hook/composable/service to wrap - the React, Vue, Svelte, and
11
11
  Solid entry points are plain re-exports of the same `core`.
12
12
 
13
13
  ## Install
@@ -24,39 +24,39 @@ npx @symbiote-native/cli new my-app --system-ui
24
24
  npx @symbiote-native/cli add --system-ui
25
25
  ```
26
26
 
27
- Either way: installs `@symbiote-native/system-ui` and wires the native autolinking automatically —
27
+ Either way: installs `@symbiote-native/system-ui` and wires the native autolinking automatically,
28
28
  see [`@symbiote-native/cli`](../cli).
29
29
 
30
30
  <details>
31
- <summary>Manual install (no CLI — installing and wiring native autolinking by hand)</summary>
31
+ <summary>Manual install (no CLI - installing and wiring native autolinking by hand)</summary>
32
32
 
33
33
  ```bash
34
34
  npm install @symbiote-native/system-ui
35
35
  ```
36
36
 
37
37
  `expo-system-ui` and `expo-modules-core` come along as regular dependencies, pinned to exact
38
- versions — never install either yourself, and never add the `expo` meta-package to your project
38
+ versions - never install either yourself, and never add the `expo` meta-package to your project
39
39
  (it bundles its own Metro/Babel pipeline, which conflicts with this project's own).
40
40
 
41
41
  ### Required one-time step: native autolinking wiring
42
42
 
43
43
  Unlike a plain RN native module, `expo-system-ui`'s native code is discovered by
44
- `expo-modules-autolinking`, not RN's own `react-native.config.cjs` mechanism — this needs wiring
44
+ `expo-modules-autolinking`, not RN's own `react-native.config.cjs` mechanism - this needs wiring
45
45
  into the native host app **once**, covering this package and every other `expo-modules-core`
46
46
  package with zero further changes:
47
47
 
48
48
  | Platform | Touches |
49
49
  | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
50
- | iOS | `ios/Podfile` — add `use_expo_modules!` |
51
- | iOS | `AppDelegate.swift` — Expo's runtime-bootstrap hook |
52
- | Android | `settings.gradle` / `app/build.gradle` — resolve and include the Expo Gradle projects |
53
- | Android | `MainApplication.kt` — Expo's bootstrap hook, plus a hand-written native-module name map (there's no `expo` meta-package here to auto-generate one) |
50
+ | iOS | `ios/Podfile` - add `use_expo_modules!` |
51
+ | iOS | `AppDelegate.swift` - Expo's runtime-bootstrap hook |
52
+ | Android | `settings.gradle` / `app/build.gradle` - resolve and include the Expo Gradle projects |
53
+ | Android | `MainApplication.kt` - Expo's bootstrap hook, plus a hand-written native-module name map (there's no `expo` meta-package here to auto-generate one) |
54
54
 
55
55
  Full mechanics live in the `symbiote-expo-native-module` project skill. Reference
56
56
  implementation: `examples/expo-react/ios/Podfile` and
57
57
  `examples/expo-react/android/app/src/main/java/com/canaryexpo/MainApplication.kt`.
58
58
 
59
- `expo-system-ui` needs no runtime permission on either platform — it only sets/reads a stored
59
+ `expo-system-ui` needs no runtime permission on either platform - it only sets/reads a stored
60
60
  background color, nothing gated by a permission prompt.
61
61
 
62
62
  </details>
@@ -66,11 +66,11 @@ background color, nothing gated by a permission prompt.
66
66
  ```
67
67
  src/core/ setBackgroundColorAsync / getBackgroundColorAsync. native-module.ts resolves the
68
68
  native module via expo-modules-core's requireNativeModule.
69
- src/angular/ @symbiote-native/system-ui/angular — export * from '../core'
69
+ src/angular/ @symbiote-native/system-ui/angular - export * from '../core'
70
70
  ```
71
71
 
72
72
  `./react`, `./vue`, `./svelte`, and `./solid` are `exports`-map aliases straight onto
73
- `src/core/` — no physical per-framework file, since there's nothing to subscribe to or clean up.
73
+ `src/core/` - no physical per-framework file, since there's nothing to subscribe to or clean up.
74
74
  `./angular` stays a physical file/subpath since Angular ships through a separate `ngc`/AOT build
75
75
  (`build-ngc/`).
76
76
 
@@ -129,16 +129,16 @@ export class RootComponent {
129
129
  }
130
130
  ```
131
131
 
132
- There's no per-instance service to `inject()` in the Angular case — both functions are plain
132
+ There's no per-instance service to `inject()` in the Angular case - both functions are plain
133
133
  exports off the core package, called straight in the constructor or wherever the app's root is
134
- set up. These snippets mirror the real canary demo screens —
134
+ set up. These snippets mirror the real canary demo screens:
135
135
  `examples/expo-react/screens/SystemUiScreen.tsx`, `examples/expo-vue-sfc/screens/SystemUiScreen.vue`,
136
136
  `examples/expo-vue-tsx/screens/SystemUiScreen.tsx`, `examples/expo-svelte/screens/SystemUiScreen.svelte`,
137
137
  `examples/expo-solid/screens/SystemUiScreen.tsx`, `examples/expo-angular/src/screens/SystemUiScreen.ts`.
138
138
 
139
139
  ## API
140
140
 
141
- Two one-shot async functions, no event stream, no per-instance state — so the React/Vue/Angular
141
+ Two one-shot async functions, no event stream, no per-instance state - so the React/Vue/Angular
142
142
  entry points above are plain re-exports of `core` with nothing adapter-specific to add.
143
143
 
144
144
  ```ts
@@ -151,7 +151,7 @@ import {
151
151
  getBackgroundColorAsync,
152
152
  setBackgroundColorAsync,
153
153
  } from '@symbiote-native/system-ui';
154
- // or the framework-scoped entry points — identical surface, re-exported verbatim:
154
+ // or the framework-scoped entry points - identical surface, re-exported verbatim:
155
155
  import { setBackgroundColorAsync } from '@symbiote-native/system-ui/react';
156
156
  import { setBackgroundColorAsync } from '@symbiote-native/system-ui/vue';
157
157
  import { setBackgroundColorAsync } from '@symbiote-native/system-ui/svelte';
@@ -161,26 +161,36 @@ import { setBackgroundColorAsync } from '@symbiote-native/system-ui/angular';
161
161
 
162
162
  ## Notes
163
163
 
164
- - **`setBackgroundColorAsync(null)` clears the override** rather than setting an actual color —
164
+ - **`setBackgroundColorAsync(null)` clears the override** rather than setting an actual color:
165
165
  it's passed straight through to the native module without running `processColor`.
166
166
  - **On web, the raw `ColorValue` is passed through untouched** instead of being run through RN's
167
- `processColor` — matching upstream, since `processColor` is a native-color-parsing step that
167
+ `processColor` - matching upstream, since `processColor` is a native-color-parsing step that
168
168
  doesn't apply on that platform.
169
169
  - **On iOS/Android, a non-null color is run through RN's own `processColor` before reaching the
170
- native module** — the same conversion RN's style pipeline uses internally.
170
+ native module** - the same conversion RN's style pipeline uses internally.
171
+
172
+ ## Common questions
173
+
174
+ - **Where to call `setBackgroundColorAsync`?** In the root file, outside any component.
175
+ - **Follow dark and light mode?** Read the color scheme and call it again on change.
176
+ - **`getBackgroundColorAsync` returns `null`.** No root background color has been set.
177
+ - **`userInterfaceStyle` at runtime?** No, it is a native build setting.
178
+
179
+ Sources: [Expo docs: SystemUI](https://docs.expo.dev/versions/latest/sdk/system-ui/),
180
+ [Evan Bacon: root background component](https://gist.github.com/EvanBacon/d148b2425c5a0bd11b6cecb5f4b72bb8).
171
181
 
172
182
  ## Test it
173
183
 
174
- No Fabric/Descriptor angle at all — both exports here are one-shot async calls, never a view or
184
+ No Fabric/Descriptor angle at all - both exports here are one-shot async calls, never a view or
175
185
  per-instance state. Tests inject a fake native-module object in place of the real
176
- `requireNativeModule` resolution (`src/core/system-ui.test.ts`, `vitest`) — no `installFabric()`,
186
+ `requireNativeModule` resolution (`src/core/system-ui.test.ts`, `vitest`) - no `installFabric()`,
177
187
  no ViewConfig. Native rendering itself is verified on-device (see the parent
178
188
  [README](../../README.md) for the project's testing model).
179
189
 
180
190
  Native autolinking wiring for `expo-modules-core` packages is already done in all six Expo
181
191
  canary apps (`examples/expo-react`, `examples/expo-vue-sfc`, `examples/expo-vue-tsx`,
182
192
  `examples/expo-svelte`, `examples/expo-solid`, `examples/expo-angular`) via
183
- `@symbiote-native/local-auth`/`@symbiote-native/sensors` — this package reuses that same wiring
193
+ `@symbiote-native/local-auth`/`@symbiote-native/sensors` - this package reuses that same wiring
184
194
  with zero further app-side changes, since `expo-modules-autolinking` discovers any
185
195
  `expo-modules-core` package already present in `node_modules`. Each canary carries its own
186
196
  `SystemUiScreen` demo.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@symbiote-native/system-ui",
3
- "version": "3.0.2",
3
+ "version": "3.0.3",
4
4
  "description": "expo-system-ui wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. Sets and reads the root view's background color.",
5
5
  "keywords": [
6
6
  "react-native",
@@ -69,7 +69,7 @@
69
69
  },
70
70
  "dependencies": {
71
71
  "expo-system-ui": "57.0.2",
72
- "expo-modules-core": "57.0.5"
72
+ "expo-modules-core": "57.0.20"
73
73
  },
74
74
  "peerDependencies": {
75
75
  "@angular/core": ">=20",
@@ -79,12 +79,12 @@
79
79
  "solid-js": ">=1.9.0",
80
80
  "svelte": ">=5.56.0",
81
81
  "vue": ">=3.5.0",
82
- "@symbiote-native/angular": "^3.1.2",
83
- "@symbiote-native/engine": "^1.3.1",
84
- "@symbiote-native/react": "^3.0.4",
85
- "@symbiote-native/solid": "^3.0.4",
86
- "@symbiote-native/svelte": "^3.0.4",
87
- "@symbiote-native/vue": "^3.0.4"
82
+ "@symbiote-native/angular": "^3.2.0",
83
+ "@symbiote-native/engine": "^1.5.0",
84
+ "@symbiote-native/react": "^3.2.0",
85
+ "@symbiote-native/solid": "^3.1.0",
86
+ "@symbiote-native/svelte": "^3.1.0",
87
+ "@symbiote-native/vue": "^3.2.0"
88
88
  },
89
89
  "peerDependenciesMeta": {
90
90
  "@symbiote-native/angular": {
@@ -132,13 +132,13 @@
132
132
  "solid-js": "^1.9.14",
133
133
  "svelte": "^5.56.0",
134
134
  "typescript": "~6.0.0",
135
- "@symbiote-native/angular": "3.1.2",
136
- "@symbiote-native/engine": "1.3.1",
137
- "@symbiote-native/react": "3.0.4",
138
- "@symbiote-native/solid": "3.0.4",
139
- "@symbiote-native/svelte": "3.0.4",
140
- "@symbiote-native/test-utils": "0.4.4",
141
- "@symbiote-native/vue": "3.0.4"
135
+ "@symbiote-native/angular": "3.2.0",
136
+ "@symbiote-native/engine": "1.5.0",
137
+ "@symbiote-native/react": "3.2.0",
138
+ "@symbiote-native/solid": "3.1.0",
139
+ "@symbiote-native/svelte": "3.1.0",
140
+ "@symbiote-native/test-utils": "0.4.6",
141
+ "@symbiote-native/vue": "3.2.0"
142
142
  },
143
143
  "scripts": {
144
144
  "typecheck": "tsc --build",