@symbiote-native/components 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,13 @@
 # @symbiote-native/components
 
-The **framework-agnostic component layer** of [SymbioteJS](../../README.md) — pure state machines
+The **framework-agnostic component layer** of [SymbioteNative](../../README.md) — pure state machines
 and pure render functions for every visual component (`Switch`, `Modal`, `ScrollView`, the
 `FlatList`/`SectionList` family, …), written **once** and inherited by every framework adapter
 (`@symbiote-native/react`, `@symbiote-native/vue`, `@symbiote-native/angular`, and the ones after them). It
 exists so that "add component X to a new adapter" means writing a thin lifecycle + descriptor
 bridge, not re-implementing X's logic per framework.
 
-> New to SymbioteJS? The [root README](../../README.md) has the architecture. This package is
+> New to SymbioteNative? The [root README](../../README.md) has the architecture. This package is
 > "Workstream B" — the piece that makes cross-adapter feature parity **structural** instead of a
 > promise kept by hand.
 
@@ -33,6 +33,14 @@ supplies only the third:
 `Switch` is the canonical reference for a full three-layer component; `ActivityIndicator` is the
 canonical render-only reference (no state machine needed).
 
+### Install
+
+Nearly every consumer gets this transitively, through an adapter. Building a new adapter yourself:
+
+```bash
+npm install @symbiote-native/components
+```
+
 ---
 
 ## Usage

package/build/bootstrap.d.ts

@@ -0,0 +1,9 @@
+import { type IColorValue, type IDeviceEventSource, type INativeViewConfigSource } from '@symbiote-native/engine';
+export type IBootstrapHostOptions = {
+    colorProcessor?: (value: IColorValue) => unknown;
+    imageSourceResolver?: (source: unknown) => unknown;
+    deviceEventSource?: IDeviceEventSource;
+    nativeViewConfigSource?: INativeViewConfigSource;
+    debug?: boolean;
+};
+export declare function bootstrapHost(options?: IBootstrapHostOptions): void;

package/build/bootstrap.js

@@ -0,0 +1,43 @@
+// Zero-config host bootstrap for @symbiote-native/components' four RN-backed seams
+// (colorProcessor, imageSourceResolver, deviceEventSource, nativeViewConfigSource), wired from
+// real react-native in one call — collapses what every canary example currently hand-wires at
+// startup. Lives OUTSIDE the package's main barrel (see package.json's separate "./bootstrap"
+// export): react-native's own source is Flow syntax Vitest's transform can't parse, so anything
+// importing it directly must stay unreachable from the tested main index.ts.
+import { processColor, DeviceEventEmitter, Image } from 'react-native';
+import { setColorProcessor, setDeviceEventSource, setNativeViewConfigSource, } from '@symbiote-native/engine';
+import { setImageSourceResolver } from './view/render-image';
+// @ts-expect-error react-native ships no types for this internal path (plain .js) — the
+// try/catch below is what actually proves the shape, not TS.
+import * as ReactNativeViewConfigRegistry from 'react-native/Libraries/Renderer/shims/ReactNativeViewConfigRegistry';
+// Third-party Fabric views derive their events + prop processors from RN's own ViewConfig
+// registry; `get` throws for an unregistered name, so undefined is the right answer for
+// anything the registry doesn't know (our built-ins never reach here).
+function defaultNativeViewConfigSource(name) {
+    try {
+        return ReactNativeViewConfigRegistry.get(name);
+    }
+    catch {
+        return undefined;
+    }
+}
+// require('./x.png') asset ids and {uri} sources are resolved by RN's own resolver before they
+// reach the shared render fns. `source` is untyped at the setImageSourceResolver seam by design
+// (any component's resolved shape flows through it) — this is the I/O edge where it crosses
+// into RN's own typed Image API.
+function defaultImageSourceResolver(source) {
+    return Image.resolveAssetSource(source);
+}
+// IColorValue is our own structural mirror of the runtime shapes RN's processColor accepts
+// (CSS string / PlatformColor / DynamicColorIOS); RN's own ColorValue type is opaque, not
+// structurally identical, so this is the I/O edge between the two color representations.
+function defaultColorProcessor(value) {
+    return processColor(value);
+}
+export function bootstrapHost(options = {}) {
+    globalThis.__SYMBIOTE_DEBUG__ = options.debug ?? process.env.DEBUG === '1';
+    setColorProcessor(options.colorProcessor ?? defaultColorProcessor);
+    setImageSourceResolver(options.imageSourceResolver ?? defaultImageSourceResolver);
+    setDeviceEventSource(options.deviceEventSource ?? DeviceEventEmitter);
+    setNativeViewConfigSource(options.nativeViewConfigSource ?? defaultNativeViewConfigSource);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@symbiote-native/components",
-  "version": "0.1.0",
-  "description": "Framework-agnostic component logic (state machines + render functions) for SymbioteJS — written once, inherited by every adapter (React, Vue, Angular, ...).",
+  "version": "0.2.0",
+  "description": "Framework-agnostic component logic (state machines + render functions) for SymbioteNative — written once, inherited by every adapter (React, Vue, Angular, ...).",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
@@ -20,6 +20,10 @@
     ".": {
       "types": "./build/index.d.ts",
       "default": "./build/index.js"
+    },
+    "./bootstrap": {
+      "types": "./build/bootstrap.d.ts",
+      "default": "./build/bootstrap.js"
     }
   },
   "files": [
@@ -29,7 +33,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@symbiote-native/engine": "0.1.0"
+    "@symbiote-native/engine": "0.1.1"
+  },
+  "peerDependencies": {
+    "react-native": ">=0.86"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0"
   },
   "scripts": {
     "typecheck": "tsc --build",

package/build/state/drawer-layout-android.d.ts

@@ -1,22 +0,0 @@
-import { type ISymbioteEvent, type ISymbioteNode } from '@symbiote/engine';
-export type IDrawerPosition = 'left' | 'right';
-export type IDrawerLockMode = 'unlocked' | 'locked-closed' | 'locked-open';
-export type IKeyboardDismissMode = 'none' | 'on-drag';
-export type IDrawerState = 'Idle' | 'Dragging' | 'Settling';
-export interface IDrawerSlideEvent {
-    offset: number;
-}
-export interface IDrawerLayoutAndroidHandle {
-    openDrawer(): void;
-    closeDrawer(): void;
-}
-export declare const DRAWER_VIEW_NAME = "AndroidDrawerLayout";
-export declare const OPEN_DRAWER_COMMAND = "openDrawer";
-export declare const CLOSE_DRAWER_COMMAND = "closeDrawer";
-export declare const DRAWER_STATES: ReadonlyArray<IDrawerState>;
-export declare const DEFAULT_DRAWER_BACKGROUND_COLOR = "white";
-export declare const DEFAULT_DRAWER_POSITION: IDrawerPosition;
-export declare function offsetFromSlide(event: ISymbioteEvent): number;
-export declare function stateFromChange(event: ISymbioteEvent): IDrawerState;
-export declare function dispatchDrawerCommand(node: ISymbioteNode | null, command: string): void;
-export declare function buildDrawerHandle(getNode: () => ISymbioteNode | null): IDrawerLayoutAndroidHandle;

package/build/state/drawer-layout-android.js

@@ -1,53 +0,0 @@
-// DrawerLayoutAndroid: the framework-agnostic logic half. AndroidDrawerLayout is Android-only, so
-// this module holds only the platform-invariant contract every adapter shares — the drawer-position
-// / lock-mode / keyboard-dismiss / state TYPES, the native view + command NAMES, the slide/state
-// event NORMALIZATION, and the imperative open/close HANDLE. The adapter supplies only its lifecycle
-// (refs / reactivity) + the descriptor→element bridge; the view (style/prop) math lives in
-// view/render-drawer-layout-android.ts. No Platform.OS read; the adapter's filename selects the build
-// (ADR 0019). The wolf-tui twin shape is the shared state module pulled out of each reconciler.
-import { dispatchViewCommand, dlog, } from '@symbiote/engine';
-// The native view name registered by AndroidDrawerLayoutNativeComponent's
-// codegenNativeComponent('AndroidDrawerLayout'): the derive-by-default name (any non-`symbiote-*`
-// type flows through descriptorFor untouched, the engine deriving its events from the ViewConfig).
-export const DRAWER_VIEW_NAME = 'AndroidDrawerLayout';
-export const OPEN_DRAWER_COMMAND = 'openDrawer';
-export const CLOSE_DRAWER_COMMAND = 'closeDrawer';
-// RN's drawerState int -> string mapping (android DRAWER_STATES indexed by the native drawerState):
-// 0=Idle, 1=Dragging, 2=Settling.
-export const DRAWER_STATES = ['Idle', 'Dragging', 'Settling'];
-export const DEFAULT_DRAWER_BACKGROUND_COLOR = 'white';
-export const DEFAULT_DRAWER_POSITION = 'left';
-// Slide-event normalization: pull the native drag offset (RN onDrawerSlide nativeEvent.offset).
-export function offsetFromSlide(event) {
-    const offset = event.nativeEvent.offset;
-    return typeof offset === 'number' ? offset : 0;
-}
-// State-change normalization: map the native drawerState int onto its DRAWER_STATES label.
-export function stateFromChange(event) {
-    const index = event.nativeEvent.drawerState;
-    if (typeof index === 'number' && index >= 0 && index < DRAWER_STATES.length) {
-        return DRAWER_STATES[index];
-    }
-    return 'Idle';
-}
-// Issue a drawer command against the committed host node, or log a silent no-op when there is no
-// node yet (the first render has not committed). Mirrors Switch's dispatchViewCommand path.
-export function dispatchDrawerCommand(node, command) {
-    if (node === null) {
-        dlog(`DrawerLayoutAndroid ${command} no-op: no committed host node`);
-        return;
-    }
-    dlog(`DrawerLayoutAndroid dispatch ${command}`);
-    dispatchViewCommand(node, command, []);
-}
-// The imperative handle is identical across adapters: openDrawer / closeDrawer dispatch the matching
-// view command on the SAME host node. Built once here; each adapter backs it with its lazy node
-// getter (React `() => ref.current`, Vue `() => nodeRef.value`), read on every call — the node is
-// null until the element commits, so an eager capture would freeze null and every command no-op.
-// The Vue twin of React's useImperativeHandle(ref, …); mirrors buildScrollViewHandle.
-export function buildDrawerHandle(getNode) {
-    return {
-        openDrawer: () => dispatchDrawerCommand(getNode(), OPEN_DRAWER_COMMAND),
-        closeDrawer: () => dispatchDrawerCommand(getNode(), CLOSE_DRAWER_COMMAND),
-    };
-}

package/build/view/render-drawer-layout-android.d.ts

@@ -1,23 +0,0 @@
-import type { IStyleProp, IViewStyle } from '@symbiote/engine';
-import { type IDrawerLockMode, type IDrawerPosition, type IKeyboardDismissMode } from '../state/drawer-layout-android';
-export declare const DRAWER_HOST_STYLE: Readonly<IViewStyle>;
-export declare const DRAWER_MAIN_SUBVIEW_STYLE: Readonly<IViewStyle>;
-export interface IDrawerLayoutResolveInput {
-    drawerWidth?: number;
-    drawerPosition?: IDrawerPosition;
-    drawerLockMode?: IDrawerLockMode;
-    keyboardDismissMode?: IKeyboardDismissMode;
-    drawerBackgroundColor?: string;
-    statusBarBackgroundColor?: string;
-    drawerOpened: boolean;
-    style?: IStyleProp<IViewStyle>;
-    passthrough: Record<string, unknown>;
-}
-export interface IDrawerLayoutResolved {
-    viewName: string;
-    hostProps: Record<string, unknown>;
-    contentWrapperStyle: Readonly<IViewStyle>;
-    navigationWrapperStyle: IViewStyle;
-    navigationPointerEvents: 'auto' | 'none';
-}
-export declare function resolveDrawerLayout(input: IDrawerLayoutResolveInput): IDrawerLayoutResolved;

package/build/view/render-drawer-layout-android.js

@@ -1,56 +0,0 @@
-// DrawerLayoutAndroid: the framework-agnostic view (style/prop) math. AndroidDrawerLayout is an
-// ordinary Fabric host node committing through the same childSet as the rest of the tree (like
-// Modal / Switch): a content wrapper FIRST and a navigation wrapper SECOND, mirroring RN's android
-// render order {childrenWrapper}{drawerViewWrapper}. This builds the host prop bag + the two wrapper
-// styles from the resolved props; the adapter overlays its ref + the wrapped event handlers and
-// supplies the framework children / navigation elements. The logic half (event normalization,
-// imperative handle, constants, types) lives in state/drawer-layout-android.ts.
-import { DEFAULT_DRAWER_BACKGROUND_COLOR, DEFAULT_DRAWER_POSITION, DRAWER_VIEW_NAME, } from '../state/drawer-layout-android';
-// RN styles.base on the host: flex:1 plus the Android drop-shadow that floats the drawer over
-// content (android styles.base { flex:1, elevation:16 }).
-export const DRAWER_HOST_STYLE = {
-    flex: 1,
-    elevation: 16,
-};
-// RN styles.mainSubview: the content wrapper fills the host (absolute, all edges 0).
-export const DRAWER_MAIN_SUBVIEW_STYLE = {
-    position: 'absolute',
-    top: 0,
-    left: 0,
-    right: 0,
-    bottom: 0,
-};
-// RN styles.drawerSubview: the navigation wrapper is absolute and full-height; its width comes from
-// drawerWidth and its background from drawerBackgroundColor (both folded in by resolveDrawerLayout).
-const DRAWER_SUBVIEW_STYLE = {
-    position: 'absolute',
-    top: 0,
-    bottom: 0,
-};
-// Build the AndroidDrawerLayout host prop bag + the two wrapper styles from the resolved props. The
-// adapter overlays its ref + the four wrapped event handlers (onDrawerOpen / Close / Slide /
-// StateChanged) and nests [contentWrapper, navigationWrapper] under the host IN THAT ORDER.
-export function resolveDrawerLayout(input) {
-    const drawerBackgroundColor = input.drawerBackgroundColor ?? DEFAULT_DRAWER_BACKGROUND_COLOR;
-    const hostProps = {
-        ...input.passthrough,
-        drawerWidth: input.drawerWidth,
-        drawerPosition: input.drawerPosition ?? DEFAULT_DRAWER_POSITION,
-        drawerLockMode: input.drawerLockMode,
-        keyboardDismissMode: input.keyboardDismissMode,
-        drawerBackgroundColor,
-        statusBarBackgroundColor: input.statusBarBackgroundColor,
-        style: [DRAWER_HOST_STYLE, input.style],
-    };
-    return {
-        viewName: DRAWER_VIEW_NAME,
-        hostProps,
-        contentWrapperStyle: DRAWER_MAIN_SUBVIEW_STYLE,
-        navigationWrapperStyle: {
-            ...DRAWER_SUBVIEW_STYLE,
-            width: input.drawerWidth,
-            backgroundColor: drawerBackgroundColor,
-        },
-        navigationPointerEvents: input.drawerOpened ? 'auto' : 'none',
-    };
-}