@symbiote-native/react 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @symbiote-native/react
 
-The **React adapter** for [SymbioteJS](../../README.md) — drive real native iOS/Android views from
+The **React adapter** for [SymbioteNative](../../README.md) — drive real native iOS/Android views from
 React, with React Native's own renderer never in the path. It is a `react-reconciler` host config
 in **mutation mode** (`appendChild` / `insertBefore` / `removeChild` → the engine's four-call
 mutation API); `@symbiote-native/engine` does the clone-on-write commit into Fabric.
@@ -11,15 +11,28 @@ adapter, not the core.
 
 <div align="center">
 
-![React driving real native iOS views through SymbioteJS](../../assets/react-demo.gif)
+![React driving real native iOS views through SymbioteNative](../../assets/react-demo.gif)
 
 </div>
 
-> New to SymbioteJS? The [root README](../../README.md) has the architecture and the one fact it
+> New to SymbioteNative? The [root README](../../README.md) has the architecture and the one fact it
 > rests on — React is just *one client* of `nativeFabricUIManager`.
 
 ---
 
+## Install
+
+```bash
+npm install @symbiote-native/react react-native react
+```
+
+`react-native` and `react` stay your app's own top-level dependencies — SymbioteNative doesn't hide
+them, it only replaces the JS renderer that drives them. There's no `create-symbiote` scaffolder
+yet, so the Metro config and the `index.js` entry seam below come from
+[`examples/react`](../../examples/react) rather than a generator.
+
+---
+
 ## Use it
 
 The app is ordinary React — it imports primitives from `@symbiote-native/react`, not `react-native`:
@@ -85,7 +98,7 @@ path (R1 + R2 + R3 — decision record 0009):
   `interpolate` · `ValueXY` · tracking · `diffClamp`). Native offload is proven by jamming the JS
   thread 1.5 s: the native-driven animations keep moving, the JS-driven one stalls (ADR 0016 · 0017).
 - **Third-party native views** — `@react-native-community/slider` used straight from the package
-  with zero SymbioteJS metadata; the engine derives its events and prop processors from the library's
+  with zero SymbioteNative metadata; the engine derives its events and prop processors from the library's
   own ViewConfig at runtime — the "install the package, use its component" path.
 - **Gestures & events** — the responder lifecycle (grant/move/release/terminate, LCA-scoped
   re-negotiation), two-phase capture→bubble delivery, `Pressable` press-retention, `Touchable*`
@@ -100,7 +113,7 @@ path (R1 + R2 + R3 — decision record 0009):
 ### Android
 
 The same canary runs on an Android emulator through the same `@symbiote-native/engine` core. Two signals
-RN ties to a view host SymbioteJS bypasses — or never shipped on Android — are re-supplied by a small
+RN ties to a view host SymbioteNative bypasses — or never shipped on Android — are re-supplied by a small
 `@symbiote-native/android` native package (`KeyboardObserver` host shim; `SettingsManager` →
 `SharedPreferences`). `Platform` and the component-name map are Metro-split per OS (`.ios` /
 `.android`), so there is no `Platform.OS` runtime branch. iOS stays the reference surface (more
@@ -145,5 +158,5 @@ npm run e2e:test:ios           # run the canary journeys on the iOS simulator
 # …or the android equivalents: e2e:build:android / e2e:test:android
 ```
 
-Why these come for free — a SymbioteJS app is a stock RN app underneath, so RN's whole testing
+Why these come for free — a SymbioteNative app is a stock RN app underneath, so RN's whole testing
 ecosystem applies unchanged. See [Testing](../../README.md#testing).

package/build/bootstrap.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentType } from 'react';
+import { type IBootstrapHostOptions } from '@symbiote-native/components/bootstrap';
+export type { IBootstrapHostOptions } from '@symbiote-native/components/bootstrap';
+export type IRegisterAppOptions = IBootstrapHostOptions & {
+    appName: string;
+};
+export declare function registerApp(App: ComponentType<object>, options: IRegisterAppOptions): void;

package/build/bootstrap.js

@@ -0,0 +1,17 @@
+// Zero-config app entry: wires the four RN-backed host seams (via @symbiote-native/components'
+// bootstrapHost) plus this adapter's own AppRegistry host-registrar bridge, then registers the
+// root component — collapsing the canary's manual sequence into one call. Lives OUTSIDE the
+// package's main barrel (see package.json's "./bootstrap" export): it imports react-native
+// directly, which Vitest's Flow-unaware transform can't parse (see
+// @symbiote-native/components/bootstrap for the full reason).
+import { AppRegistry as RNAppRegistry } from 'react-native';
+import { bootstrapHost } from '@symbiote-native/components/bootstrap';
+import { AppRegistry, setHostRegistrar } from './modules/app-registry';
+// Mirrors bare RN's own `AppRegistry.registerComponent(appName, () => App)` idiom, minus the
+// manual host wiring in front of it.
+export function registerApp(App, options) {
+    const { appName, ...bootstrapOptions } = options;
+    bootstrapHost(bootstrapOptions);
+    setHostRegistrar(RNAppRegistry);
+    AppRegistry.registerComponent(appName, () => App);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@symbiote-native/react",
-  "version": "0.1.0",
-  "description": "SymbioteJS's React adapter — a react-reconciler host config (mutation mode) driving real native iOS/Android views through stock React Native Fabric.",
+  "version": "0.2.0",
+  "description": "SymbioteNative's React adapter — a react-reconciler host config (mutation mode) driving real native iOS/Android views through stock React Native Fabric.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
@@ -21,6 +21,10 @@
       "types": "./build/index.d.ts",
       "default": "./build/index.js"
     },
+    "./bootstrap": {
+      "types": "./build/bootstrap.d.ts",
+      "default": "./build/bootstrap.js"
+    },
     "./metro-css-parser": "./metro-css-parser.cjs"
   },
   "files": [
@@ -32,9 +36,9 @@
   },
   "dependencies": {
     "react-reconciler": "^0.33.0",
-    "@symbiote-native/components": "0.1.0",
-    "@symbiote-native/engine": "0.1.0",
-    "@symbiote-native/css-parser": "0.1.0"
+    "@symbiote-native/components": "0.2.0",
+    "@symbiote-native/css-parser": "0.1.1",
+    "@symbiote-native/engine": "0.1.1"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
@@ -44,7 +48,7 @@
     "@types/react": "^19.2.0",
     "@types/react-reconciler": "^0.32.2",
     "react": "19.2.3",
-    "@symbiote-native/test-utils": "0.0.0"
+    "@symbiote-native/test-utils": "0.1.1"
   },
   "scripts": {
     "typecheck": "tsc --build",

package/build/components/drawer-layout-android/index.android.d.ts

@@ -1,3 +0,0 @@
-import type { IDrawerLayoutAndroidHandle, IDrawerLayoutAndroidProps } from './shared';
-export type { IDrawerPosition, IDrawerLockMode, IKeyboardDismissMode, IDrawerState, IDrawerSlideEvent, IDrawerLayoutAndroidProps, IDrawerLayoutAndroidHandle, } from './shared';
-export declare const DrawerLayoutAndroid: import("react").ForwardRefExoticComponent<IDrawerLayoutAndroidProps & import("react").RefAttributes<IDrawerLayoutAndroidHandle>>;

package/build/components/drawer-layout-android/index.android.js

@@ -1,93 +0,0 @@
-// DrawerLayoutAndroid: the real Android build. AndroidDrawerLayout is an ordinary
-// Fabric host node: it lives in the SAME childSet and commits through the SAME
-// completeRoot as the rest of the tree, exactly like Modal/Switch. There is no
-// per-library glue; shared derives the view's events/processors from its ViewConfig,
-// so we render the RAW Fabric name `AndroidDrawerLayout` (the derive-by-default path:
-// any non-`symbiote-*` createElement type flows through untouched).
-//
-// Behavior mirrors RN's DrawerLayoutAndroid.android.js: the navigation view (from
-// `renderNavigationView()`) and the main content are wrapped in two container Views,
-// and, critically, the child order RN commits is [mainSubview, drawerSubview]: the
-// content wrapper FIRST, the navigation wrapper SECOND (android render:
-// {childrenWrapper}{drawerViewWrapper}). The navigation wrapper is absolutely
-// positioned, drawerWidth-wide, and gated by pointerEvents so it stays untouchable
-// until opened. `openDrawer`/`closeDrawer` are imperative, reached through a ref, and
-// dispatched as the `openDrawer`/`closeDrawer` view commands against the host node,
-// mirroring Switch's dispatchViewCommand path (Commands.openDrawer/closeDrawer in
-// AndroidDrawerLayoutNativeComponent).
-//
-// The platform-invariant math — the host prop bag + the content/navigation wrapper styles, the
-// slide/state event normalization, the imperative open/close handle, and the view/command NAMES —
-// lives in @symbiote/components, shared verbatim with the Vue adapter; here React supplies only the
-// lifecycle: a ref holds the host node, a `drawerOpened` state gates the navigation wrapper's
-// pointerEvents, and useImperativeHandle wires the imperative handle.
-//
-// Metro picks this file on an Android host; off Android the base index.ts
-// renders the fallback. No Platform.OS read; the filename is the selector (ADR 0019).
-// device-verify-pending: the `AndroidDrawerLayout` name + the openDrawer/closeDrawer
-// commands are RN-source-confirmed, not yet exercised on a real Android host.
-import { createElement, forwardRef, useCallback, useImperativeHandle, useRef, useState, } from 'react';
-import { dlog } from '@symbiote/engine';
-import { buildDrawerHandle, DEFAULT_DRAWER_POSITION, offsetFromSlide, resolveAccessibilityProps, resolveDrawerLayout, stateFromChange, } from '@symbiote/components';
-import { View } from '../../components';
-export const DrawerLayoutAndroid = forwardRef((props, ref) => {
-    const { drawerWidth, drawerPosition, drawerLockMode, keyboardDismissMode, drawerBackgroundColor, statusBarBackgroundColor, onDrawerOpen, onDrawerClose, onDrawerSlide, onDrawerStateChanged, renderNavigationView, style, children, ...passthrough } = props;
-    const node = useRef(null);
-    // RN tracks drawerOpened to gate the navigation view's pointerEvents (android
-    // _onDrawerOpen/_onDrawerClose setState). Closed -> 'none' so the off-screen drawer
-    // never intercepts touches; open -> 'auto' (folded in by resolveDrawerLayout).
-    const [drawerOpened, setDrawerOpened] = useState(false);
-    // The imperative handle reads the node through a LAZY getter (() => node.current), not the node
-    // captured once: it is null until the element commits. The React twin of Vue's
-    // expose(buildDrawerHandle(…)).
-    useImperativeHandle(ref, () => buildDrawerHandle(() => node.current), []);
-    const handleDrawerOpen = useCallback(() => {
-        dlog('DrawerLayoutAndroid onDrawerOpen');
-        setDrawerOpened(true);
-        onDrawerOpen?.();
-    }, [onDrawerOpen]);
-    const handleDrawerClose = useCallback(() => {
-        dlog('DrawerLayoutAndroid onDrawerClose');
-        setDrawerOpened(false);
-        onDrawerClose?.();
-    }, [onDrawerClose]);
-    const handleDrawerSlide = useCallback((event) => {
-        onDrawerSlide?.({ offset: offsetFromSlide(event) });
-    }, [onDrawerSlide]);
-    const handleDrawerStateChanged = useCallback((event) => {
-        onDrawerStateChanged?.(stateFromChange(event));
-    }, [onDrawerStateChanged]);
-    const resolved = resolveDrawerLayout({
-        drawerWidth,
-        drawerPosition,
-        drawerLockMode,
-        keyboardDismissMode,
-        drawerBackgroundColor,
-        statusBarBackgroundColor,
-        drawerOpened,
-        style,
-        // The drawer renders a raw host node (not the View FC), so unlike View-backed components nothing
-        // else resolves aria-*/role — fold them into accessibility* here before passing through.
-        passthrough: resolveAccessibilityProps(passthrough),
-    });
-    // RN's mainSubview: content wrapped in an absolute box.
-    const contentWrapper = createElement(View, { style: resolved.contentWrapperStyle }, children);
-    // RN's drawerSubview: the navigation view wrapped, drawerWidth-wide, painted with
-    // drawerBackgroundColor, untouchable until opened.
-    const navigationWrapper = createElement(View, {
-        style: resolved.navigationWrapperStyle,
-        pointerEvents: resolved.navigationPointerEvents,
-    }, renderNavigationView());
-    dlog(`DrawerLayoutAndroid render position=${drawerPosition ?? DEFAULT_DRAWER_POSITION} ` +
-        `width=${String(drawerWidth)} opened=${drawerOpened}`);
-    // Child order matches RN exactly: content FIRST, navigation SECOND
-    // (android render emits {childrenWrapper}{drawerViewWrapper}).
-    return createElement(resolved.viewName, {
-        ...resolved.hostProps,
-        ref: node,
-        onDrawerOpen: handleDrawerOpen,
-        onDrawerClose: handleDrawerClose,
-        onDrawerSlide: handleDrawerSlide,
-        onDrawerStateChanged: handleDrawerStateChanged,
-    }, contentWrapper, navigationWrapper);
-});

package/build/components/drawer-layout-android/index.d.ts

@@ -1,3 +0,0 @@
-import type { IDrawerLayoutAndroidHandle, IDrawerLayoutAndroidProps } from './shared';
-export type { IDrawerPosition, IDrawerLockMode, IKeyboardDismissMode, IDrawerState, IDrawerSlideEvent, IDrawerLayoutAndroidProps, IDrawerLayoutAndroidHandle, } from './shared';
-export declare const DrawerLayoutAndroid: import("react").ForwardRefExoticComponent<IDrawerLayoutAndroidProps & import("react").RefAttributes<IDrawerLayoutAndroidHandle>>;

package/build/components/drawer-layout-android/index.js

@@ -1,19 +0,0 @@
-// DrawerLayoutAndroid: base / off-Android fallback. AndroidDrawerLayout is Android-
-// only, so everywhere except an Android host (where Metro picks
-// drawer-layout-android.android.ts) we render the content in a plain container and drop
-// the navigation view (RN's DrawerLayoutAndroidFallback shape). The imperative
-// open/close are silent no-ops; there is no drawer to drive. The filename is the
-// selector; no Platform.OS read. The barrel imports './drawer-layout-android', which
-// resolves here under tsc/tsx and to the .android file under Metro. See ADR 0019.
-import { createElement, forwardRef, useImperativeHandle } from 'react';
-import { dlog } from '@symbiote/engine';
-import { View } from '../../components';
-export const DrawerLayoutAndroid = forwardRef((props, ref) => {
-    const { style, children } = props;
-    useImperativeHandle(ref, () => ({
-        openDrawer: () => dlog('DrawerLayoutAndroid.openDrawer no-op: off Android'),
-        closeDrawer: () => dlog('DrawerLayoutAndroid.closeDrawer no-op: off Android'),
-    }), []);
-    dlog('DrawerLayoutAndroid fallback: off-Android host, rendering content only');
-    return createElement(View, { style }, children);
-});

package/build/components/drawer-layout-android/shared.d.ts

@@ -1,19 +0,0 @@
-import type { ReactNode } from 'react';
-import type { IAccessibilityProps, IAriaProps, IDrawerLockMode, IDrawerPosition, IDrawerSlideEvent, IDrawerState, IKeyboardDismissMode } from '@symbiote/components';
-import type { IStyleProp, IViewStyle } from '../../utils/styles';
-export type { IDrawerPosition, IDrawerLockMode, IKeyboardDismissMode, IDrawerState, IDrawerSlideEvent, IDrawerLayoutAndroidHandle, } from '@symbiote/components';
-export interface IDrawerLayoutAndroidProps extends IAccessibilityProps, IAriaProps {
-    drawerWidth?: number;
-    drawerPosition?: IDrawerPosition;
-    drawerLockMode?: IDrawerLockMode;
-    keyboardDismissMode?: IKeyboardDismissMode;
-    drawerBackgroundColor?: string;
-    statusBarBackgroundColor?: string;
-    onDrawerOpen?: () => void;
-    onDrawerClose?: () => void;
-    onDrawerSlide?: (event: IDrawerSlideEvent) => void;
-    onDrawerStateChanged?: (state: IDrawerState) => void;
-    renderNavigationView: () => ReactNode;
-    style?: IStyleProp<IViewStyle>;
-    children?: ReactNode;
-}

package/build/components/drawer-layout-android/shared.js

@@ -1,7 +0,0 @@
-// Shared types for the React DrawerLayoutAndroid: the same Props/Handle contract the real Android
-// build (index.android.ts) and the off-Android fallback (index.ts) both implement. The
-// platform-agnostic enums + the imperative handle live in @symbiote/components (the single source of
-// truth, shared verbatim with the Vue adapter); this file adds only the React-facing prop surface and
-// re-exports the agnostic types so the barrel and both builds keep importing them from one local path.
-// Per ADR 0019 the filename selects the build; no Platform.OS read anywhere.
-export {};