@viewfly/core 2.2.0 → 3.0.0-alpha.0

package/dist/base/_api.d.ts

@@ -4,7 +4,6 @@ export * from './dep';
 export * from './injection-tokens';
 export * from './jsx-element';
 export * from './lifecycle';
-export * from './memo';
 export * from './ref';
 export * from './renderer';
 export * from './root.component';

package/dist/base/component.d.ts

@@ -1,18 +1,17 @@
-import { Key, Props } from './jsx-element';
+import { Key } from './jsx-element';
 import { NativeNode } from './injection-tokens';
 import { JSX } from './types';
 import { LifeCycleCallback } from './lifecycle';
 import { ComponentAtom } from './_utils';
 export declare function getSetupContext(need?: boolean): Component;
 export type ClassNames = string | Record<string, unknown> | false | null | undefined | ClassNames[];
-export interface ComponentInstance<P> {
+export interface ComponentInstance {
     $portalHost?: NativeNode;
     $render(): JSXNode;
-    $useMemo?(currentProps: P, prevProps: P): boolean;
 }
 export type JSXNode = JSX.Element | JSX.ElementClass | string | number | boolean | null | undefined | Iterable<JSXNode>;
 export interface ComponentSetup<P = any> {
-    (props: P): (() => JSXNode) | ComponentInstance<P>;
+    (props: P): (() => JSXNode) | ComponentInstance;
 }
 export interface ComponentViewMetadata {
     atom: ComponentAtom;
@@ -28,7 +27,7 @@ export declare class Component {
     readonly type: ComponentSetup;
     props: Record<string, any>;
     readonly key?: Key;
-    instance: ComponentInstance<Props>;
+    instance: ComponentInstance;
     changedSubComponents: Set<Component>;
     get dirty(): boolean;
     get changed(): boolean;
@@ -44,14 +43,13 @@ export declare class Component {
     protected _changed: boolean;
     private isFirstRendering;
     private rawProps;
-    private refs;
+    private refEffects;
     private listener;
     constructor(parentComponent: Component | null, type: ComponentSetup, props: Record<string, any>, key?: Key);
     markAsDirtied(): void;
     markAsChanged(changedComponent?: Component): void;
     render(update: (template: JSXNode, portalHost?: NativeNode) => void): void;
     updateProps(newProps: Record<string, any>): void;
-    canUpdate(oldProps: Record<string, any>, newProps: Record<string, any>): boolean;
     rerender(): JSXNode;
     destroy(): void;
     rendered(): void;
@@ -60,6 +58,20 @@ export declare class Component {
 }
 /**
  * 获取当前组件实例
+ * @returns 当前组件实例
+ * @example
+ * ```tsx
+ * function App() {
+ *   const instance = getCurrentInstance()
+ *   console.log(instance)
+ *   return () => <div>...</div>
+ * }
+ * ```
  */
 export declare function getCurrentInstance(): Component;
+/**
+ * 注册组件销毁回调函数
+ * @param fn 要注册的回调函数
+ * @internal
+ */
 export declare function registryComponentDestroyCallback(fn: () => void): void;

package/dist/base/context.d.ts

@@ -1,6 +1,36 @@
 import { AbstractType, ClassProvider, ExistingProvider, ExtractValueType, FactoryProvider, InjectFlags, InjectionToken, Injector, Provider, Scope, Type, ValueProvider } from '../di/_api';
 import { Props } from './jsx-element';
 import { ComponentSetup } from './component';
+/**
+ * 创建一个上下文，用于在组件之间共享数据
+ * @param providers 提供者，用于提供数据
+ * @param scope 作用域，用于限制提供者的作用域
+ * @param parentInjector 父注入器，用于自定义父注入器，默认从当前组件树中自动获取
+ * @returns 一个上下文组件，组件的子元素都可以通过 inject 获取到提供者提供的数据
+ * @example
+ * ```tsx
+ * @Injectable()
+ * class ExampleService {}
+ *
+ * function Child(props) {
+ *   const exampleService = inject(ExampleService)
+ *   console.log(exampleService)
+ *   return () => {
+ *     return <div>{props.children}</div>
+ *   }
+ * }
+ * function App() {
+ *   const Context = createContext([
+ *     ExampleService
+ *   ])
+ *   return () => {
+ *     return <Context>
+ *       <Child>test</Child>
+ *     </Context>
+ *   }
+ * }
+ * ```
+ */
 export declare function createContext(providers: Provider[], scope?: Scope | null, parentInjector?: Injector): (props: Props) => () => import('./component').JSXNode | import('./component').JSXNode[];
 export interface ContextProviderParams<T> {
     provide: Type<T> | AbstractType<T> | InjectionToken<T>;
@@ -11,9 +41,49 @@ export interface ContextProvider<T> extends Props {
     useValue?: ValueProvider<T>['useValue'];
     useExisting?: ExistingProvider<T>['useExisting'];
 }
+/**
+ * 创建一个上下文提供者组件，组件的子元素都可以通过 inject 获取到提供者提供的数据
+ * @param params 提供者参数
+ * @returns 一个上下文提供者组件，组件的子元素都可以通过 inject 获取到提供者提供的数据
+ * @example
+ * ```tsx
+ * const ExampleService = createContextProvider({
+ *   provide: ExampleService
+ * })
+ *
+ * function Child() {
+ *   const exampleService = inject(ExampleService)
+ *   console.log(exampleService)
+ *   return () => {
+ *     return <div>{exampleService.name}</div>
+ *   }
+ * }
+ *
+ * function App() {
+ *   const value = new ExampleService()
+ *   return () => {
+ *     return <ExampleService useValue={value}>
+ *       <Child/>
+ *     </ExampleService>
+ *   }
+ * }
+ */
 export declare function createContextProvider<T>(params: ContextProviderParams<T>): (props: ContextProvider<T>) => () => import('./jsx-element').ViewFlyNode<string | ComponentSetup<any>>;
 /**
  * 通过组件上下文获取 IoC 容器内数据的勾子方法
+ * @param token 注入的 token
+ * @param notFoundValue 未找到时的值
+ * @param flags 注入标志
+ * @returns 注入的值
+ * @example
+ * ```tsx
+ * function ChildComponent() {
+ *   const exampleService = inject(ExampleService)
+ *   console.log(exampleService)
+ *   return () => {
+ *     return <div>{exampleService.name}</div>
+ *   }
+ * }
  */
 export declare function inject<T extends Type<any> | AbstractType<any> | InjectionToken<any>, U = never>(token: T, notFoundValue?: U, flags?: InjectFlags): ExtractValueType<T> | U;
 export interface ComponentAnnotation {

package/dist/base/jsx-element.d.ts

@@ -4,7 +4,7 @@ export interface Props {
     children?: JSXNode | JSXNode[];
 }
 export declare function Fragment(props: Props): () => JSXNode | JSXNode[];
-export type Key = number | string;
+export type Key = any;
 export declare function jsx(type: string | ComponentSetup, props: Props & Record<string, any>, key?: Key): ViewFlyNode;
 export declare const jsxs: typeof jsx;
 export interface ViewFlyNode<T = string | ComponentSetup> {

package/dist/base/lifecycle.d.ts

@@ -2,12 +2,17 @@ export interface LifeCycleCallback {
     (): void | (() => void);
 }
 /**
- * 当组件第一次渲染完成时触发
- * @param callback
+ * 当组件挂载后调用回调函数
+ * @param callback 回调函数
+ * @returns 一个函数，用于停止监听
+ * @example
  * ```tsx
  * function App() {
- *   onMount(() => {
+ *   onMounted(() => {
  *     console.log('App mounted!')
+ *     return () => {
+ *       console.log('destroy prev mount!')
+ *     }
  *   })
  *   return () => <div>...</div>
  * }
@@ -15,8 +20,10 @@ export interface LifeCycleCallback {
  */
 export declare function onMounted(callback: LifeCycleCallback): void;
 /**
- * 当组件视图更新后调用
- * @param callback
+ * 当组件视图更新后调用回调函数
+ * @param callback 回调函数
+ * @returns 一个函数，用于停止监听
+ * @example
  * ```tsx
  * function App() {
  *   onUpdated(() => {
@@ -31,7 +38,17 @@ export declare function onMounted(callback: LifeCycleCallback): void;
  */
 export declare function onUpdated(callback: LifeCycleCallback): () => void;
 /**
- * 当组件销毁时调用回调函数
- * @param callback
+ * 当组件销毁后调用回调函数
+ * @param callback 回调函数
+ * @returns 一个函数，用于停止监听
+ * @example
+ * ```tsx
+ * function App() {
+ *   onUnmounted(() => {
+ *     console.log('App unmounted!')
+ *   })
+ *   return () => <div>...</div>
+ * }
+ * ```
  */
 export declare function onUnmounted(callback: () => void): void;

package/dist/base/ref.d.ts

@@ -1,44 +1,50 @@
 import { ComponentInstance } from './component';
-export interface RefListener<T> {
-    (current: T): void | (() => void);
-}
-export type ExtractInstanceType<T, U = T extends (...args: any) => any ? ReturnType<T> : T> = U extends ComponentInstance<any> ? Omit<U, keyof ComponentInstance<any>> : U extends Function ? never : T;
-export interface AbstractInstanceType<T extends Record<string, any>> {
-    (): T & ComponentInstance<any>;
-}
-export declare class DynamicRef<T> {
-    private callback;
-    private unBindMap;
-    private targetCaches;
-    constructor(callback: RefListener<T>);
-    bind(value: T): void;
-    unBind(value: T): void;
+import { RefProp } from './types';
+export type ExtractInstanceType<T, U = T extends (...args: any) => any ? ReturnType<T> : T> = U extends ComponentInstance ? Omit<U, keyof ComponentInstance> : U extends Function ? never : T;
+export interface DynamicRef<T> {
+    (value: T): void | (() => void);
 }
 /**
- * 用于节点渲染完成时获取 DOM 节点
- * @param callback 获取 DOM 节点的回调函数
+ * 创建一个动态 ref，当 ref 的绑定的元素或组件初始化后，会调用副作用函数，并把元素或组件的实例作为参数传入。
+ * @param effect 用于接收实例的副作用函数，该函数还可以返回一个清理副作用的函数，当元素或组件销毁时调用
+ * @returns 一个函数，用于清理副作用
  * @example
  * ```tsx
  * function App() {
- *   const ref = createDynamicRef(node => {
- *     function fn() {
- *       // do something...
- *     }
- *     node.addEventListener('click', fn)
+ *   const ref = createDynamicRef<HTMLDivElement>((node) => {
+ *     console.log(node)
  *     return () => {
- *       node.removeEventListener('click', fn)
+ *       console.log('destroy')
  *     }
  *   })
  *   return () => {
- *     return <div ref={ref}>xxx</div>
+ *     return <div ref={ref}>test</div>
  *   }
  * }
  * ```
  */
-export declare function createDynamicRef<T, U = ExtractInstanceType<T>>(callback: RefListener<U>): DynamicRef<U>;
-export declare class StaticRef<T> extends DynamicRef<T> {
-    get current(): T | null;
-    private _current;
-    constructor();
-}
-export declare function createRef<T, U = ExtractInstanceType<T>>(): StaticRef<U>;
+export declare function createDynamicRef<T, U = ExtractInstanceType<T>>(effect: DynamicRef<U>): DynamicRef<U>;
+export type Ref<T> = {
+    readonly value: T;
+};
+/**
+ * 创建一个引用对象，并添加到 JSX 节点上属性上，当组件渲染后，即可通过 .value 获取到绑定节点的实例
+ * - 当绑定到虚拟 DOM 元素节点上时，value 为当前节点的 DOM 元素
+ * - 当绑定到组件节点上时，value 为组件函数返回的对象
+ * @example
+ * ```tsx
+ * function App() {
+ *   const ref = createRef<HTMLDivElement>()
+ *   onMounted(() => {
+ *      console.log(ref.value)
+ *   })
+ *   return () => {
+ *     return <div ref={ref}>...</div>
+ *   }
+ * }
+ * ```
+ */
+export declare function createRef<T, U = ExtractInstanceType<T> | null>(): Ref<U | null>;
+export type RefEffects = Map<RefProp<any>, (() => void) | void>;
+export declare function applyRefs(ref: RefProp<any> | RefProp<any>[], value: object, refEffects: RefEffects): void;
+export declare function updateRefs(ref: RefProp<any> | RefProp<any>[], value: object, refEffects: RefEffects): void;

package/dist/base/types.d.ts

@@ -1,6 +1,7 @@
 import { Key, ViewFlyNode } from './jsx-element';
 import { ComponentInstance, ComponentSetup } from './component';
-import { DynamicRef, ExtractInstanceType } from './ref';
+import { DynamicRef, ExtractInstanceType, Ref } from './ref';
+export type RefProp<T> = Ref<ExtractInstanceType<T> | null> | DynamicRef<ExtractInstanceType<T>>;
 export declare namespace JSX {
     type ElementType = keyof IntrinsicElements | ComponentSetup;
     interface Element extends ViewFlyNode {
@@ -10,12 +11,8 @@ export declare namespace JSX {
     }
     interface IntrinsicAttributes extends KeyedAttributes {
         ref?: any;
-        [key: string]: any;
     }
-    interface RefAttributes<T> extends KeyedAttributes {
-        ref?: DynamicRef<ExtractInstanceType<T>> | DynamicRef<ExtractInstanceType<T>>[];
-    }
-    interface ElementClass<P = any> extends ComponentInstance<P> {
+    interface ElementClass extends ComponentInstance {
     }
     interface ElementAttributesProperty {
         props: {};
@@ -27,6 +24,6 @@ export declare namespace JSX {
         [name: string]: any;
     }
     interface IntrinsicClassAttributes<T> {
-        ref?: DynamicRef<T>;
+        ref?: RefProp<T>;
     }
 }

package/dist/index.d.ts

@@ -3,4 +3,3 @@ export * from './_utils/make-error';
 export * from './base/_api';
 export * from './viewfly';
 export * from './reactive/_api';
-export * from './signals/_api';