@symbiote-native/react 3.0.1 → 3.0.3

package/README.md

@@ -22,43 +22,75 @@ adapter, not the core.
 
 ## Install
 
+```bash
+npx @symbiote-native/cli new my-app --framework react
+```
+
+One command, nothing to wire by hand: scaffolds the Metro config, the entry seam below, and
+`@symbiote-native/react`/`react-native`/`react` as your app's own dependencies.
+
+<details>
+<summary>Manual install (no generator — an existing app, or you want to wire it yourself)</summary>
+
 ```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. `npx @symbiote-native/cli new --framework react`
-scaffolds the Metro config and the `index.js` entry seam below for a new app; wiring them into an
-existing one still follows [`examples/react`](../../examples/react) rather than a generator.
+them, it only replaces the JS renderer that drives them. Follow [`examples/react`](../../examples/react)
+for the Metro config and the entry seam below; there is no wiring script for an existing app.
+
+</details>
 
 ---
 
 ## Use it
 
-The app is ordinary React — the native primitives are plain intrinsic tags, no import needed:
+The app is ordinary React — the native primitives are plain intrinsic tags, no import needed.
+Styling is a CSS class against a plain `.css` file, the convention every example app here
+follows (`StyleSheet.create` still works, but isn't what any example uses):
 
 ```jsx
 import { useState } from 'react';
+import './App.css';
 
 export default function App() {
   const [count, setCount] = useState(0);
   return (
-    <view style={{ padding: 24 }}>
+    <safe-area-view className="screen">
       <text>Taps: {count}</text>
       <pressable onPress={() => setCount(c => c + 1)}>
         <text>Tap me</text>
       </pressable>
-    </view>
+    </safe-area-view>
   );
 }
 ```
 
+```css
+/* App.css */
+.screen {
+  flex: 1;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+}
+```
+
+<details>
+<summary>Native entry point (index.js) — already scaffolded by <code>npx @symbiote-native/cli new</code></summary>
+
 The zero-config entry wires the RN-backed host seams (colors, images, device events,
 third-party ViewConfigs) and registers the app in one call — this is what
 [`examples/react`](../../examples/react) actually uses:
 
 ```js
 // index.js
+
+// Registers host behaviors (Image, Pressable, Switch, ...) that /bootstrap alone doesn't
+// reach; deleting this breaks them silently (Metro's production inlineRequires makes a
+// side-effect-only barrel import go lazy, see register.ts).
+import '@symbiote-native/react';
 import { registerApp } from '@symbiote-native/react/bootstrap';
 import App from './App';
 import { name as appName } from './app.json';
@@ -91,6 +123,8 @@ AppRegistry.registerRunnable(appName, ({ rootTag }) => {
 });
 ```
 
+</details>
+
 Either way, the full canary ([`App.tsx`](../../examples/react/App.tsx)) exercises every block of
 the surface below.
 
@@ -141,8 +175,9 @@ the future scaffolder).
 
 ## Run it
 
-[`examples/react`](../../examples/react) is a stock React Native 0.86 app. Requires Node ≥ 22 and
-the [RN environment setup](https://reactnative.dev/docs/set-up-your-environment) (Xcode, CocoaPods):
+[`examples/react`](../../examples/react) is a stock React Native 0.86 app. Requires Node ≥ 22.13
+(react-native 0.86's own `package.json#engines`) and the [RN environment
+setup](https://reactnative.dev/docs/set-up-your-environment) (Xcode, CocoaPods):
 
 ```bash
 cd examples/react

package/build/components/flat-list/index.d.ts

@@ -66,6 +66,8 @@ export interface IFlatListProps<ItemT> extends IAccessibilityProps, IAriaProps {
     style?: IStyleProp<IViewStyle>;
     contentContainerStyle?: IStyleProp<IViewStyle>;
     className?: string;
+    removeClippedSubviews?: boolean;
+    nestedScrollEnabled?: boolean;
 }
 export declare function FlatList<ItemT>(props: IFlatListProps<ItemT> & {
     ref?: Ref<IFlatListHandle>;

package/build/components/flat-list/index.js

@@ -6,8 +6,8 @@
 // transforms are shared from @symbiote-native/components. This file only adapts to React's lifecycle
 // (element creation + ref threading).
 import { createElement, } from 'react';
-import { dlog, resolveClassName, } from '@symbiote-native/engine';
-import { SINGLE_COLUMN, chunkIntoRows, expandRowViewability, firstItemOfRow, lastItemOfRow, rowKeyExtractor, } from '@symbiote-native/components';
+import { Platform, dlog, resolveClassName, } from '@symbiote-native/engine';
+import { SINGLE_COLUMN, chunkIntoRows, expandRowViewability, firstItemOfRow, lastItemOfRow, removeClippedSubviewsOrDefault, rowKeyExtractor, } from '@symbiote-native/components';
 import { VirtualizedList, } from '../virtualized-list/index.js';
 export function FlatList(props) {
     const { ref, data, renderItem, keyExtractor, numColumns = SINGLE_COLUMN, columnWrapperStyle, 
@@ -16,7 +16,12 @@ export function FlatList(props) {
     onViewableItemsChanged, viewabilityConfigCallbackPairs, 
     // ItemSeparatorComponent is typed on ItemT; the multi-column stream is IRow<ItemT>, so it is
     // wrapped there to unwrap rows back to items, exactly like viewability above.
-    ItemSeparatorComponent, ...rest } = props;
+    ItemSeparatorComponent, removeClippedSubviews: authoredRemoveClippedSubviews, ...ownRest } = props;
+    // FlatList.js always sends it, defaulted per platform.
+    const rest = {
+        ...ownRest,
+        removeClippedSubviews: removeClippedSubviewsOrDefault(authoredRemoveClippedSubviews, Platform.OS),
+    };
     dlog(`FlatList over ${data.length} items, ${numColumns} column(s)`);
     if (numColumns <= SINGLE_COLUMN) {
         return createElement((VirtualizedList), {

package/build/components/keyboard-avoiding-view/index.js

@@ -68,7 +68,7 @@ export const KeyboardAvoidingView = props => {
             for (const subscription of subscriptions)
                 subscription.remove();
         };
-    }, [behavior, keyboardVerticalOffset]);
+    }, [behavior, keyboardVerticalOffset, enabled]);
     const handleLayout = (event) => {
         const frame = readLayoutFrame(event.nativeEvent.layout);
         if (frame !== undefined) {

package/build/components/modal/index.js

@@ -12,8 +12,8 @@
 // through the exit transition. The native exit-animation timing is what's deferred, not the
 // callback contract.
 import { createElement, useEffect, useReducer, } from 'react';
-import { dlog } from '@symbiote-native/engine';
-import { createInitialModalState, modalReducer, renderModal, resolveAccessibilityProps, shouldRenderModal, } from '@symbiote-native/components';
+import { dlog, Platform } from '@symbiote-native/engine';
+import { createInitialModalState, isModalVisible, modalReducer, modalVisibilityAction, renderModal, resolveAccessibilityProps, shouldRenderModal, } from '@symbiote-native/components';
 export const Modal = rawProps => {
     // Modal owns its host element (modal), so it folds aria/role here; the resolved fields
     // ride the host node via `...passthrough`. The events (onShow/onDismiss/onRequestClose/
@@ -21,18 +21,26 @@ export const Modal = rawProps => {
     // className is pulled out here, like style, and applied to the CONTAINER element below — left in
     // ...passthrough it would land on the outer modal host instead (renderModal composes
     // `style` into the container's style, not the host's).
-    const { visible, transparent, backdropColor, animationType, presentationStyle, supportedOrientations, hardwareAccelerated, statusBarTranslucent, navigationBarTranslucent, allowSwipeDismissal, style, className, children, ...passthrough } = resolveAccessibilityProps(rawProps);
-    // The iOS keep-alive: the effect runs AFTER this render, so a visible→hidden transition keeps the
-    // node mounted for one frame (state.isRendered still true here) before the next render unmounts it,
-    // the same shape as RN's componentDidUpdate setState (see state/modal.ts).
-    const [state, dispatch] = useReducer(modalReducer, visible === true, createInitialModalState);
+    const { visible, transparent, backdropColor, animationType, presentationStyle, supportedOrientations, hardwareAccelerated, statusBarTranslucent, navigationBarTranslucent, allowSwipeDismissal, style, className, children, onDismiss, ...passthrough } = resolveAccessibilityProps(rawProps);
+    // The iOS keep-alive (state/modal.ts): armed on show, dropped only by the native dismiss below.
+    const isVisible = isModalVisible(visible);
+    const [state, dispatch] = useReducer(modalReducer, isVisible, createInitialModalState);
     useEffect(() => {
-        dispatch(visible === true ? { type: 'show' } : { type: 'hide' });
-    }, [visible]);
-    if (!shouldRenderModal(visible === true, state)) {
+        const action = modalVisibilityAction(isVisible);
+        if (action !== undefined)
+            dispatch(action);
+    }, [isVisible]);
+    if (!shouldRenderModal(isVisible, state)) {
         dlog('Modal hidden -> no node committed');
         return null;
     }
+    // Modal.js: onDismiss is iOS-only — it drops the keep-alive, then tells the app.
+    const handleDismiss = () => {
+        if (Platform.OS !== 'ios')
+            return;
+        dispatch({ type: 'hide' });
+        onDismiss?.();
+    };
     const root = renderModal({
         visible,
         transparent,
@@ -45,7 +53,7 @@ export const Modal = rawProps => {
         navigationBarTranslucent,
         allowSwipeDismissal,
         style,
-        passthrough,
+        passthrough: { ...passthrough, onDismiss: handleDismiss },
     });
     // root = modal > [container]; the user children nest UNDER the container View, never as
     // a direct sibling of the host (RN's modal content layout).

package/build/components/virtualized-list/index.d.ts

@@ -64,6 +64,8 @@ export interface IVirtualizedListProps<ItemT> extends IAccessibilityProps, IAria
     scrollEventThrottle?: number;
     keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
     keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+    removeClippedSubviews?: boolean;
+    nestedScrollEnabled?: boolean;
     style?: IStyleProp<IViewStyle>;
     contentContainerStyle?: IStyleProp<IViewStyle>;
     className?: string;

package/build/components/virtualized-list/index.js

@@ -146,7 +146,7 @@ export function VirtualizedList(props) {
         }
         dlog(`VirtualizedList scrollTo offset=${clamped} pending-ref (horizontal=${isHorizontal})`);
         setCommandedOffset(target);
-    }, []);
+    }, [scrollHandle]);
     // dispatch and runEffects are mutually recursive (a schedule-refill / fire-viewable effect
     // dispatches a follow-up action), so runEffects reaches dispatch through a ref.
     const dispatchRef = useRef(() => { });
@@ -491,8 +491,9 @@ export function VirtualizedList(props) {
     const resolvedContentContainerStyle = horizontal
         ? [contentContainerStyle, { width: total }]
         : contentContainerStyle;
+    // VirtualizedList.js: `[inversionStyle, style]` — the app's style can override the flip.
     const resolvedStyle = inverted
-        ? [style, horizontal ? INVERTED_X_STYLE : INVERTED_Y_STYLE]
+        ? [horizontal ? INVERTED_X_STYLE : INVERTED_Y_STYLE, style]
         : style;
     const scrollProps = {
         // The list's accessibility surface rides down onto the ScrollView. Spread first so the
@@ -507,6 +508,9 @@ export function VirtualizedList(props) {
     // scrolls the two axes with different native ViewManagers. The behavior's own fold deletes the
     // prop and rewrites it from the tag, so passing it would be at best redundant and at worst a
     // contradiction it has to warn about.
+    // VirtualizedList.js:1111 — Android moves the scrollbar back after the `scale: -1` flip.
+    if (inverted)
+        scrollProps.isInvertedVirtualizedList = true;
     if (onScrollBeginDrag !== undefined)
         scrollProps.onScrollBeginDrag = onScrollBeginDrag;
     if (onScrollEndDrag !== undefined)

package/build/components/virtualized-section-list/index.d.ts

@@ -62,6 +62,8 @@ export interface IVirtualizedSectionListProps<ItemT> extends IAccessibilityProps
     scrollEventThrottle?: number;
     keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
     keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+    removeClippedSubviews?: boolean;
+    nestedScrollEnabled?: boolean;
     style?: IStyleProp<IViewStyle>;
     contentContainerStyle?: IStyleProp<IViewStyle>;
     className?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/react",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "SymbioteNative's React adapter — a react-reconciler host config (mutation mode) driving real native iOS/Android views through stock React Native Fabric.",
   "license": "MIT",
   "repository": {
@@ -57,20 +57,20 @@
   },
   "dependencies": {
     "react-reconciler": "^0.33.0",
-    "@symbiote-native/components": "3.0.1",
-    "@symbiote-native/css-parser": "0.5.0"
+    "@symbiote-native/components": "3.1.1",
+    "@symbiote-native/css-parser": "0.5.1"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
     "react-native": ">=0.86",
-    "@symbiote-native/engine": "^1.2.0"
+    "@symbiote-native/engine": "^1.3.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.0",
     "@types/react-reconciler": "^0.32.2",
     "react": "19.2.3",
-    "@symbiote-native/engine": "1.2.0",
-    "@symbiote-native/test-utils": "0.4.1"
+    "@symbiote-native/engine": "1.3.0",
+    "@symbiote-native/test-utils": "0.4.3"
   },
   "scripts": {
     "typecheck": "tsc --build",