@virentia/react 0.1.1 → 0.2.0

package/README.md

@@ -75,6 +75,23 @@ export const Counter = component({
 });
 ```
 
+`component` also exposes `.create()` and accepts a `model` prop for controlled usage.
+The created model owns its scope and should be disposed by the caller.
+
+```tsx
+const Parent = component({
+  model() {
+    const counter = Counter.create({ step: 2 });
+
+    return { counter };
+  },
+
+  view({ model }) {
+    return <Counter step={2} model={model.counter} />;
+  },
+});
+```
+
 ## Model Caches
 
 Use `createModelCache` when a model should survive unmount and be reused by key: chats, tabs, detail screens, media players, or previews.

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let react = require("react");
 let _virentia_core = require("@virentia/core");
+let react = require("react");
 //#region lib/model-cache.ts
 function createModelCache() {
 	const byScope = /* @__PURE__ */ new WeakMap();
@@ -91,6 +91,9 @@ function useProvidedScope() {
 	if (!scope) throw new Error("[useProvidedScope] Scope is not provided. Wrap your tree with ScopeProvider.");
 	return scope;
 }
+function useOptionalProvidedScope() {
+	return (0, react.useContext)(ScopeContext);
+}
 //#endregion
 //#region lib/utils.ts
 const useIsomorphicLayoutEffect = typeof window === "undefined" ? react.useEffect : react.useLayoutEffect;
@@ -177,7 +180,8 @@ function useStoreUnit(unit, scope) {
 function useModel(modelOrFactory, props, options) {
 	const scope = useProvidedScope();
 	if (typeof modelOrFactory !== "function") return useReactiveModel(modelOrFactory, scope);
-	return useReactiveModel(useModelInstance(modelOrFactory, props, scope, options).model, scope);
+	const instance = useModelInstance(modelOrFactory, props, scope, options);
+	return useReactiveModel(instance.model, instance.scope);
 }
 function useModelInstance(factory, props, scope, options) {
 	const cache = options?.cache;
@@ -191,6 +195,11 @@ function useModelInstance(factory, props, scope, options) {
 		key,
 		scope
 	]);
+	useModelInstanceLifecycle(instance, props, { disposeOnUnmount: !cached });
+	return instance;
+}
+function useModelInstanceLifecycle(instance, props, options) {
+	const scope = instance.scope;
 	useIsomorphicLayoutEffect(() => {
 		writeStore(instance.props, props, scope);
 	}, [
@@ -208,14 +217,13 @@ function useModelInstance(factory, props, scope, options) {
 				instance.mounts.value = Math.max(0, instance.mounts.value - 1);
 				instance.unmounted();
 			});
-			if (!cached) instance.dispose();
+			if (options.disposeOnUnmount) instance.dispose();
 		};
 	}, [
-		cached,
 		instance,
+		options.disposeOnUnmount,
 		scope
 	]);
-	return instance;
 }
 function createModelInstance(factory, props, scope, key) {
 	return (0, _virentia_core.owner)((dispose, modelOwner) => {
@@ -236,34 +244,83 @@ function createModelInstance(factory, props, scope, key) {
 		};
 	});
 }
+function exposeModelInstance(instance) {
+	const model = instance.model;
+	Object.defineProperty(model, modelInstanceSymbol, {
+		configurable: true,
+		value: instance
+	});
+	defineHidden(model, "dispose", () => instance.dispose());
+	defineHidden(model, disposeSymbol, () => instance.dispose());
+	return model;
+}
+function readExposedModelInstance(model) {
+	return model[modelInstanceSymbol] ?? null;
+}
 function useReactiveModel(model, scope) {
 	const result = {};
 	for (const key of Reflect.ownKeys(model)) {
-		if (key === "dispose" || key === disposeSymbol) continue;
+		const descriptor = Reflect.getOwnPropertyDescriptor(model, key);
+		if (key === "dispose" || key === disposeSymbol || descriptor && !descriptor.enumerable) continue;
 		result[key] = useModelValue(Reflect.get(model, key), scope);
 	}
 	return result;
 }
 const disposeSymbol = typeof Symbol.dispose === "symbol" ? Symbol.dispose : Symbol.for("Symbol.dispose");
+const modelInstanceSymbol = Symbol("virentia.react.modelInstance");
+function defineHidden(target, key, value) {
+	if (key in target) return;
+	Object.defineProperty(target, key, {
+		configurable: true,
+		value
+	});
+}
 function useModelValue(value, scope) {
 	if (isUnitLike(value)) return useUnitWithScope(value, scope);
+	if (isComponentModel(value)) return value;
 	if (isPlainObject(value)) return useReactiveModel(value, scope);
 	return value;
 }
+function isComponentModel(value) {
+	return Boolean(value && typeof value === "object" && value[modelInstanceSymbol]);
+}
 //#endregion
 //#region lib/component.ts
 function component(config) {
 	const VirentiaComponent = (props) => {
-		const model = "cache" in config ? useModel(config.model, props, {
-			cache: config.cache,
-			key: config.key(props)
-		}) : useModel(config.model, props);
+		const { model: controlledModel, ...modelProps } = props;
+		const providedScope = useOptionalProvidedScope();
+		const controlledInstance = controlledModel ? readExposedModelInstance(controlledModel) : null;
+		const key = "cache" in config ? config.key(modelProps) : void 0;
+		const instance = (0, react.useMemo)(() => {
+			if (controlledModel) {
+				if (!controlledInstance) throw new Error("[component] The model prop must be created with component.create().");
+				return controlledInstance;
+			}
+			if (!providedScope) throw new Error("[useProvidedScope] Scope is not provided. Wrap your tree with ScopeProvider.");
+			if ("cache" in config) return getOrCreateCachedInstance(config.cache, providedScope, key, () => createModelInstance(config.model, modelProps, providedScope, key));
+			return createModelInstance(config.model, modelProps, providedScope, void 0);
+		}, [
+			controlledInstance,
+			controlledModel,
+			key,
+			providedScope
+		]);
+		const cached = !controlledModel && "cache" in config;
+		const model = useReactiveModel(instance.model, instance.scope);
+		useModelInstanceLifecycle(instance, modelProps, { disposeOnUnmount: !controlledModel && !cached });
 		return (0, react.createElement)(config.view, {
-			...props,
+			...modelProps,
 			model
 		});
 	};
 	VirentiaComponent.displayName = getComponentName(config.view);
+	VirentiaComponent.create = ((props) => {
+		const externalScope = (0, _virentia_core.getCurrentScope)();
+		if (!externalScope) throw new Error("[component.create] Parent component context is required. Call .create() while creating a parent component model.");
+		const key = "cache" in config ? config.key(props) : void 0;
+		return exposeModelInstance(createModelInstance(config.model, props, externalScope, key));
+	});
 	return VirentiaComponent;
 }
 //#endregion

package/dist/index.d.cts

@@ -1,10 +1,11 @@
+import { DisposableOwner, Effect, EffectCallArgs, EventCallable, EventPayload, Owner, Scope, Store, StoreWritable } from "@virentia/core";
 import { ComponentType, FC, ReactNode } from "react";
-import { Effect, EffectCallArgs, EventCallable, EventPayload, Owner, Scope, Store, StoreWritable } from "@virentia/core";
 
 //#region lib/types.d.ts
 type UnitLike = Store<any> | StoreWritable<any> | EventCallable<any> | Effect<any, any, any>;
+declare const componentModelBrand: unique symbol;
 type UnitValue<Unit> = Unit extends Store<infer State> | StoreWritable<infer State> ? State : Unit extends EventCallable<infer Payload> ? (...payload: EventPayload<Payload>) => Promise<void> : Unit extends Effect<infer Params, infer Done, any> ? (...args: EffectCallArgs<Params>) => Promise<Done> : never;
-type ReactiveModel<Model> = { readonly [Key in keyof Model as Key extends "dispose" ? never : Key]: Model[Key] extends UnitLike ? UnitValue<Model[Key]> : Model[Key] extends ((...args: any[]) => any) ? Model[Key] : Model[Key] extends object ? ReactiveModel<Model[Key]> : Model[Key] };
+type ReactiveModel<Model> = { readonly [Key in keyof Model as Key extends "dispose" ? never : Key]: Model[Key] extends ComponentModel<infer ChildModel> ? ComponentModel<ChildModel> : Model[Key] extends UnitLike ? UnitValue<Model[Key]> : Model[Key] extends ((...args: any[]) => any) ? Model[Key] : Model[Key] extends object ? ReactiveModel<Model[Key]> : Model[Key] };
 interface ModelContext<Props, Key = undefined> {
   readonly scope: Scope;
   readonly owner: Owner;
@@ -31,6 +32,18 @@ type CacheOptions<Props, Key, Model extends object> = {
   readonly cache: ModelCache<Key, Props, Model>;
   readonly key: Key;
 };
+type ComponentModel<Model extends object> = Model & DisposableOwner & {
+  readonly [componentModelBrand]: true;
+};
+type ComponentPublicProps<Props, Model extends object> = Omit<Props, "model"> & {
+  readonly model?: ComponentModel<Model>;
+};
+interface ComponentCreate<Props, Model extends object> {
+  (props: Props): ComponentModel<Model>;
+}
+type VirentiaComponent<Props, Model extends object> = FC<ComponentPublicProps<Props, Model>> & {
+  readonly create: ComponentCreate<Props, Model>;
+};
 type ComponentConfig<Props, Model extends object> = {
   readonly model: ModelFactory<Props, Model>;
   readonly view: ComponentType<Props & {
@@ -47,8 +60,8 @@ type CachedComponentConfig<Props, Key, Model extends object> = {
 };
 //#endregion
 //#region lib/component.d.ts
-declare function component<Props, Model extends object>(config: ComponentConfig<Props, Model>): FC<Props>;
-declare function component<Props, Key, Model extends object>(config: CachedComponentConfig<Props, Key, Model>): FC<Props>;
+declare function component<Props, Model extends object>(config: ComponentConfig<Props, Model>): VirentiaComponent<Props, Model>;
+declare function component<Props, Key, Model extends object>(config: CachedComponentConfig<Props, Key, Model>): VirentiaComponent<Props, Model>;
 //#endregion
 //#region lib/model-cache.d.ts
 declare function createModelCache<Key, Props, Model extends object>(): ModelCache<Key, Props, Model>;
@@ -73,4 +86,4 @@ declare function useUnit<Params, Done, Fail>(unit: Effect<Params, Done, Fail>):
 declare function useUnit<const Shape extends readonly UnitLike[]>(shape: Shape): UnitShape<Shape>;
 declare function useUnit<const Shape extends Record<string, UnitLike>>(shape: Shape): UnitShape<Shape>;
 //#endregion
-export { type ModelCache, type ModelContext, type ModelFactory, type ModelInstance, type ReactiveModel, ScopeProvider, type UnitLike, type UnitValue, component, createModelCache, useModel, useProvidedScope, useUnit };
+export { type ComponentCreate, type ComponentModel, type ComponentPublicProps, type ModelCache, type ModelContext, type ModelFactory, type ModelInstance, type ReactiveModel, ScopeProvider, type UnitLike, type UnitValue, type VirentiaComponent, component, createModelCache, useModel, useProvidedScope, useUnit };

package/dist/index.d.mts

@@ -1,10 +1,11 @@
+import { DisposableOwner, Effect, EffectCallArgs, EventCallable, EventPayload, Owner, Scope, Store, StoreWritable } from "@virentia/core";
 import { ComponentType, FC, ReactNode } from "react";
-import { Effect, EffectCallArgs, EventCallable, EventPayload, Owner, Scope, Store, StoreWritable } from "@virentia/core";
 
 //#region lib/types.d.ts
 type UnitLike = Store<any> | StoreWritable<any> | EventCallable<any> | Effect<any, any, any>;
+declare const componentModelBrand: unique symbol;
 type UnitValue<Unit> = Unit extends Store<infer State> | StoreWritable<infer State> ? State : Unit extends EventCallable<infer Payload> ? (...payload: EventPayload<Payload>) => Promise<void> : Unit extends Effect<infer Params, infer Done, any> ? (...args: EffectCallArgs<Params>) => Promise<Done> : never;
-type ReactiveModel<Model> = { readonly [Key in keyof Model as Key extends "dispose" ? never : Key]: Model[Key] extends UnitLike ? UnitValue<Model[Key]> : Model[Key] extends ((...args: any[]) => any) ? Model[Key] : Model[Key] extends object ? ReactiveModel<Model[Key]> : Model[Key] };
+type ReactiveModel<Model> = { readonly [Key in keyof Model as Key extends "dispose" ? never : Key]: Model[Key] extends ComponentModel<infer ChildModel> ? ComponentModel<ChildModel> : Model[Key] extends UnitLike ? UnitValue<Model[Key]> : Model[Key] extends ((...args: any[]) => any) ? Model[Key] : Model[Key] extends object ? ReactiveModel<Model[Key]> : Model[Key] };
 interface ModelContext<Props, Key = undefined> {
   readonly scope: Scope;
   readonly owner: Owner;
@@ -31,6 +32,18 @@ type CacheOptions<Props, Key, Model extends object> = {
   readonly cache: ModelCache<Key, Props, Model>;
   readonly key: Key;
 };
+type ComponentModel<Model extends object> = Model & DisposableOwner & {
+  readonly [componentModelBrand]: true;
+};
+type ComponentPublicProps<Props, Model extends object> = Omit<Props, "model"> & {
+  readonly model?: ComponentModel<Model>;
+};
+interface ComponentCreate<Props, Model extends object> {
+  (props: Props): ComponentModel<Model>;
+}
+type VirentiaComponent<Props, Model extends object> = FC<ComponentPublicProps<Props, Model>> & {
+  readonly create: ComponentCreate<Props, Model>;
+};
 type ComponentConfig<Props, Model extends object> = {
   readonly model: ModelFactory<Props, Model>;
   readonly view: ComponentType<Props & {
@@ -47,8 +60,8 @@ type CachedComponentConfig<Props, Key, Model extends object> = {
 };
 //#endregion
 //#region lib/component.d.ts
-declare function component<Props, Model extends object>(config: ComponentConfig<Props, Model>): FC<Props>;
-declare function component<Props, Key, Model extends object>(config: CachedComponentConfig<Props, Key, Model>): FC<Props>;
+declare function component<Props, Model extends object>(config: ComponentConfig<Props, Model>): VirentiaComponent<Props, Model>;
+declare function component<Props, Key, Model extends object>(config: CachedComponentConfig<Props, Key, Model>): VirentiaComponent<Props, Model>;
 //#endregion
 //#region lib/model-cache.d.ts
 declare function createModelCache<Key, Props, Model extends object>(): ModelCache<Key, Props, Model>;
@@ -73,4 +86,4 @@ declare function useUnit<Params, Done, Fail>(unit: Effect<Params, Done, Fail>):
 declare function useUnit<const Shape extends readonly UnitLike[]>(shape: Shape): UnitShape<Shape>;
 declare function useUnit<const Shape extends Record<string, UnitLike>>(shape: Shape): UnitShape<Shape>;
 //#endregion
-export { type ModelCache, type ModelContext, type ModelFactory, type ModelInstance, type ReactiveModel, ScopeProvider, type UnitLike, type UnitValue, component, createModelCache, useModel, useProvidedScope, useUnit };
+export { type ComponentCreate, type ComponentModel, type ComponentPublicProps, type ModelCache, type ModelContext, type ModelFactory, type ModelInstance, type ReactiveModel, ScopeProvider, type UnitLike, type UnitValue, type VirentiaComponent, component, createModelCache, useModel, useProvidedScope, useUnit };

package/dist/index.mjs

@@ -1,5 +1,5 @@
+import { event, getCurrentScope, owner, run, scoped, store } from "@virentia/core";
 import { createContext, createElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from "react";
-import { event, owner, run, scoped, store } from "@virentia/core";
 //#region lib/model-cache.ts
 function createModelCache() {
 	const byScope = /* @__PURE__ */ new WeakMap();
@@ -90,6 +90,9 @@ function useProvidedScope() {
 	if (!scope) throw new Error("[useProvidedScope] Scope is not provided. Wrap your tree with ScopeProvider.");
 	return scope;
 }
+function useOptionalProvidedScope() {
+	return useContext(ScopeContext);
+}
 //#endregion
 //#region lib/utils.ts
 const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
@@ -176,7 +179,8 @@ function useStoreUnit(unit, scope) {
 function useModel(modelOrFactory, props, options) {
 	const scope = useProvidedScope();
 	if (typeof modelOrFactory !== "function") return useReactiveModel(modelOrFactory, scope);
-	return useReactiveModel(useModelInstance(modelOrFactory, props, scope, options).model, scope);
+	const instance = useModelInstance(modelOrFactory, props, scope, options);
+	return useReactiveModel(instance.model, instance.scope);
 }
 function useModelInstance(factory, props, scope, options) {
 	const cache = options?.cache;
@@ -190,6 +194,11 @@ function useModelInstance(factory, props, scope, options) {
 		key,
 		scope
 	]);
+	useModelInstanceLifecycle(instance, props, { disposeOnUnmount: !cached });
+	return instance;
+}
+function useModelInstanceLifecycle(instance, props, options) {
+	const scope = instance.scope;
 	useIsomorphicLayoutEffect(() => {
 		writeStore(instance.props, props, scope);
 	}, [
@@ -207,14 +216,13 @@ function useModelInstance(factory, props, scope, options) {
 				instance.mounts.value = Math.max(0, instance.mounts.value - 1);
 				instance.unmounted();
 			});
-			if (!cached) instance.dispose();
+			if (options.disposeOnUnmount) instance.dispose();
 		};
 	}, [
-		cached,
 		instance,
+		options.disposeOnUnmount,
 		scope
 	]);
-	return instance;
 }
 function createModelInstance(factory, props, scope, key) {
 	return owner((dispose, modelOwner) => {
@@ -235,34 +243,83 @@ function createModelInstance(factory, props, scope, key) {
 		};
 	});
 }
+function exposeModelInstance(instance) {
+	const model = instance.model;
+	Object.defineProperty(model, modelInstanceSymbol, {
+		configurable: true,
+		value: instance
+	});
+	defineHidden(model, "dispose", () => instance.dispose());
+	defineHidden(model, disposeSymbol, () => instance.dispose());
+	return model;
+}
+function readExposedModelInstance(model) {
+	return model[modelInstanceSymbol] ?? null;
+}
 function useReactiveModel(model, scope) {
 	const result = {};
 	for (const key of Reflect.ownKeys(model)) {
-		if (key === "dispose" || key === disposeSymbol) continue;
+		const descriptor = Reflect.getOwnPropertyDescriptor(model, key);
+		if (key === "dispose" || key === disposeSymbol || descriptor && !descriptor.enumerable) continue;
 		result[key] = useModelValue(Reflect.get(model, key), scope);
 	}
 	return result;
 }
 const disposeSymbol = typeof Symbol.dispose === "symbol" ? Symbol.dispose : Symbol.for("Symbol.dispose");
+const modelInstanceSymbol = Symbol("virentia.react.modelInstance");
+function defineHidden(target, key, value) {
+	if (key in target) return;
+	Object.defineProperty(target, key, {
+		configurable: true,
+		value
+	});
+}
 function useModelValue(value, scope) {
 	if (isUnitLike(value)) return useUnitWithScope(value, scope);
+	if (isComponentModel(value)) return value;
 	if (isPlainObject(value)) return useReactiveModel(value, scope);
 	return value;
 }
+function isComponentModel(value) {
+	return Boolean(value && typeof value === "object" && value[modelInstanceSymbol]);
+}
 //#endregion
 //#region lib/component.ts
 function component(config) {
 	const VirentiaComponent = (props) => {
-		const model = "cache" in config ? useModel(config.model, props, {
-			cache: config.cache,
-			key: config.key(props)
-		}) : useModel(config.model, props);
+		const { model: controlledModel, ...modelProps } = props;
+		const providedScope = useOptionalProvidedScope();
+		const controlledInstance = controlledModel ? readExposedModelInstance(controlledModel) : null;
+		const key = "cache" in config ? config.key(modelProps) : void 0;
+		const instance = useMemo(() => {
+			if (controlledModel) {
+				if (!controlledInstance) throw new Error("[component] The model prop must be created with component.create().");
+				return controlledInstance;
+			}
+			if (!providedScope) throw new Error("[useProvidedScope] Scope is not provided. Wrap your tree with ScopeProvider.");
+			if ("cache" in config) return getOrCreateCachedInstance(config.cache, providedScope, key, () => createModelInstance(config.model, modelProps, providedScope, key));
+			return createModelInstance(config.model, modelProps, providedScope, void 0);
+		}, [
+			controlledInstance,
+			controlledModel,
+			key,
+			providedScope
+		]);
+		const cached = !controlledModel && "cache" in config;
+		const model = useReactiveModel(instance.model, instance.scope);
+		useModelInstanceLifecycle(instance, modelProps, { disposeOnUnmount: !controlledModel && !cached });
 		return createElement(config.view, {
-			...props,
+			...modelProps,
 			model
 		});
 	};
 	VirentiaComponent.displayName = getComponentName(config.view);
+	VirentiaComponent.create = ((props) => {
+		const externalScope = getCurrentScope();
+		if (!externalScope) throw new Error("[component.create] Parent component context is required. Call .create() while creating a parent component model.");
+		const key = "cache" in config ? config.key(props) : void 0;
+		return exposeModelInstance(createModelInstance(config.model, props, externalScope, key));
+	});
 	return VirentiaComponent;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@virentia/react",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "",
   "keywords": [],
   "homepage": "https://movpushmov.dev/virentia/react/",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@virentia/core": "0.1.1"
+    "@virentia/core": "0.2.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",