airx 0.2.3 → 0.3.0

package/README.md

@@ -1,50 +1,56 @@
-# airx 
+# airx
 
 [![npm](https://img.shields.io/npm/v/airx.svg)](https://www.npmjs.com/package/airx) [![build status](https://github.com/airxjs/airx/actions/workflows/check.yml/badge.svg?branch=main)](https://github.com/airxjs/airx/actions/workflows/check.yml)
 
 ☁️ Airx is a lightweight JSX web application framework.
 
-Airx is a front-end framework based on JSX, designed to provide a simple and straightforward solution for building web applications. While it does not include hooks like React, it offers a range of features to manage state and handle user interactions efficiently.
+[中文文档](https://github.com/airxjs/airx/blob/main/README_CN.md)
+|
+[English Document](https://github.com/airxjs/airx/blob/main/README.md)
+
+Airx is a frontend development framework based on `JSX` and `Signal`, aimed at providing a simple and direct solution for building web applications.
 
 ## Features
 
-- Create reaction values for managing dynamic data
-- Define components using JSX syntax
-- Lightweight and easy to learn
+- Seamlessly integrates with [Signal](https://github.com/tc39/proposal-signals) and its ecosystem!
+- Developed entirely using TypeScript, TypeScript-friendly
+- Defines components using JSX functional syntax
+- No hooks like React 😊
+- Minimal API for easy learning
 
 ## Getting Started
 
-To get started with Airx, follow these steps:
+To begin using Airx, follow these steps:
 
 1. Install Airx using npm or yarn:
 
- ```shell
- npm install airx
- ```
+```shell
+npm install airx
+```
 
-2. Import the necessary functions and components in your project:
+2. Import necessary functions and components into your project:
 
 ```javascript
 import * as airx from 'airx'
 
-// create a reaction value
-const outsideCount = airx.createSignal(1)
+// All values based on Signal automatically trigger updates
+const state = new Signal.State(1)
+const computed = new Signal.Computed(() => state.get() + 100)
 
-// define a component
 function App() {
-  // create a reaction value
-  const innerCount = airx.createSignal(1)
+  const innerState = new Signal.State(1)
 
   const handleClick = () => {
-    innerCount.value += 1
-    outsideCount.value +=1
+    state.set(state.get() + 1)
+    innerState.set(innerState.get() + 1)
   }
 
-  // return a render function
+  // Return a rendering function
   return () => (
     <button onClick={handleClick}>
-      {innerCount.value}
-      {outsideCount.value}
+      {state.get()}
+      {computed.get()}
+      {innerState.get()}
     </button>
   )
 }
@@ -53,18 +59,60 @@ const app = airx.createApp(<App />);
 app.mount(document.getElementById('app'));
 ```
 
+## API
+
+We have only a few APIs because we pursue a minimal core design. In the future, we will also open up a plugin system.
+
+### createApp
+
+Create an application instance.
+
+### provide
+
+```ts
+function provide: <T = unknown>(key: unknown, value: T): ProvideUpdater<T>
+```
+
+Inject a value downwards through the `context`, must be called synchronously directly or indirectly within a component.
+
+### inject
+
+```ts
+function inject<T = unknown>(key: unknown): T | undefined
+```
+
+Look up a specified value upwards through the `context`, must be called synchronously directly or indirectly within a component.
+
+### onMounted
+
+```ts
+type MountedListener = () => (() => void) | void
+function onMounted(listener: MountedListener): void
+```
+
+Register a callback for when the DOM is mounted, must be called synchronously directly or indirectly within a component.
+
+### onUnmounted
+
+```ts
+type UnmountedListener = () => void
+function onUnmounted(listener: UnmountedListener): void
+```
+
+Register a callback for when the DOM is unmounted, must be called synchronously directly or indirectly within a component.
+
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+This project uses the MIT License. For detailed information, please refer to the [LICENSE](LICENSE) file.
 
-## Contributing
+## Contribution
 
 Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.
 
-## Acknowledgments
+## Acknowledgements
 
-We would like to thank all the contributors and supporters of the Airx project.
+We want to thank all contributors and supporters of the Airx project.
 
 ---
 
-For more information, check out the [official documentation](https://github.com/airxjs/airx).
+For more information, please refer to the [official documentation](https://github.com/airxjs/airx)

package/output/esm/element.d.ts

@@ -38,9 +38,11 @@ export interface AirxComponentLifecycle {
     onMounted: (listener: AirxComponentMountedListener) => void;
     onUnmounted: (listener: AirxComponentUnmountedListener) => void;
 }
+type ProvideUpdater<T = unknown> = (newValue: T | ((old: T) => T)) => void;
 export type AirxComponentContext = AirxComponentLifecycle & {
-    provide: <T = unknown>(key: unknown, value: T) => (newValue: T) => void;
+    provide: <T = unknown>(key: unknown, value: T) => ProvideUpdater<T>;
     inject: <T = unknown>(key: unknown) => T | undefined;
 };
 export declare function component<P = unknown>(comp: AirxComponent<P>): AirxComponent<P>;
+export declare function createErrorRender(error: unknown): AirxComponentRender;
 export {};

package/output/esm/index.d.ts

@@ -1,13 +1,14 @@
-import { AirxElement } from './element';
 import { Plugin } from './render';
+import { AirxComponent, AirxElement } from './element';
 export * from './types';
 export { Plugin } from './render';
-export { createSignal, Signal, watchSignal } from './reactive';
 export { Fragment, component, createElement, AirxComponent, AirxElement, AirxChildren, AirxComponentContext } from './element';
 export { inject, provide, onMounted, onUnmounted } from './render';
 export interface AirxApp {
-    plugin: (...plugins: Plugin[]) => AirxApp;
     mount: (container: HTMLElement) => AirxApp;
+    /** @deprecated WIP */
+    plugin: (...plugins: Plugin[]) => AirxApp;
+    /** @deprecated WIP */
     renderToHTML: () => Promise<string>;
 }
-export declare function createApp(element: AirxElement<any>): AirxApp;
+export declare function createApp(element: AirxElement<any> | AirxComponent): AirxApp;

package/output/esm/index.js

@@ -1,11 +1,11 @@
-const globalContext$1 = {
+const globalContext = {
     current: null
 };
 function useContext() {
-    if (globalContext$1.current == null) {
+    if (globalContext.current == null) {
         throw new Error('Unable to find a valid component context');
     }
-    return globalContext$1.current;
+    return globalContext.current;
 }
 const onMounted = (listener) => {
     return useContext().onMounted(listener);
@@ -20,85 +20,65 @@ const provide = (key, value) => {
     return useContext().provide(key, value);
 };
 
-const isDev = typeof process != 'undefined' && process?.env?.NODE_ENV === 'development';
+const isPrintLogs = typeof process != 'undefined'
+    && process?.env?.NODE_ENV === 'development'
+    && process?.env?.AIRX_DEBUG === 'true';
 function createLogger(name) {
     function getPrintPrefix() {
         const date = new Date().toLocaleString();
         return `[${date}][${name}]`;
     }
     function debug(...args) {
-        if (isDev)
+        if (isPrintLogs)
             console.log(getPrintPrefix(), ...args);
     }
     return { debug };
 }
 
-const airxElementSymbol = Symbol('airx-element');
-const airxReactiveDependenciesSymbol = Symbol('airx-dependencies');
-
-/** FIXME: 污染全局总是不好的 */
-const globalContext = {
-    dependencies: new Set()
-};
-function createCollector() {
-    const newDependencies = new Set();
-    return {
-        clear: () => newDependencies.clear(),
-        complete: () => [...newDependencies.values()],
-        collect: (process) => {
-            const beforeDeps = globalContext.dependencies;
-            globalContext.dependencies = newDependencies;
-            const result = process();
-            globalContext.dependencies = beforeDeps;
-            return result;
-        }
-    };
-}
-function triggerRef(ref) {
-    requestAnimationFrame(() => {
-        const deps = Reflect.get(ref, airxReactiveDependenciesSymbol);
-        for (const dep of deps) {
-            dep();
-        }
-    });
+let firstSignal = undefined;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const globalNS = (function () {
+    // the only reliable means to get the global object is
+    // `Function('return this')()`
+    // However, this causes CSP violations in Chrome apps.
+    if (typeof self !== 'undefined') {
+        return self;
+    }
+    if (typeof window !== 'undefined') {
+        return window;
+    }
+    if (typeof global !== 'undefined') {
+        return global;
+    }
+    throw new Error('unable to locate global object');
+})();
+// 通过函数包装来延迟加载 Signal
+// 这对使用 Polyfill 的应用来说更友好
+function getSignal() {
+    const globalSignal = globalNS['Signal'];
+    if (globalSignal == null)
+        throw new Error('Signal is undefined');
+    if (firstSignal == null)
+        firstSignal = globalSignal;
+    if (firstSignal !== globalSignal)
+        throw new Error('Signal have multiple instances');
+    return globalSignal;
 }
-function createRefObject(value) {
-    const object = Object.create({ value });
-    Reflect.defineProperty(object, airxReactiveDependenciesSymbol, {
-        configurable: false,
-        enumerable: false,
-        writable: true,
-        value: new Set()
-    });
-    return object;
+function createWatch(notify) {
+    const signal = getSignal();
+    return new signal.subtle.Watcher(notify);
 }
-function watchSignal(ref, listener) {
-    const deps = Reflect.get(ref, airxReactiveDependenciesSymbol);
-    deps.add(listener);
-    return () => { deps.delete(listener); };
+function createComputed(computation, options) {
+    const signal = getSignal();
+    return new signal.Computed(computation, options);
 }
-function createSignal(obj) {
-    const ref = createRefObject(obj);
-    if (!globalContext.dependencies.has(ref)) {
-        globalContext.dependencies.add(ref);
-    }
-    let value = ref.value;
-    Reflect.defineProperty(ref, 'value', {
-        get() {
-            if (!globalContext.dependencies.has(ref)) {
-                globalContext.dependencies.add(ref);
-            }
-            return value;
-        },
-        set(newValue) {
-            value = newValue;
-            triggerRef(ref);
-            return value;
-        }
-    });
-    return ref;
+function isState(target) {
+    const signal = getSignal();
+    return target instanceof signal.State;
 }
 
+const airxElementSymbol = Symbol('airx-element');
+
 /**
  * createElement 是用于创建 AirxElement 的工具函数
  */
@@ -124,6 +104,29 @@ function Fragment(props) {
 function component(comp) {
     return comp;
 }
+function createErrorRender(error) {
+    console.error(error);
+    const handleClick = () => {
+        // 点击输出错误是为了避免
+        // 页面上多个组件同时出错时
+        // 无法定位错误与之对应的组件
+        console.error(error);
+    };
+    const formattingError = () => {
+        if (error == null)
+            return 'Unknown rendering error';
+        if (error instanceof Error)
+            return error.message;
+        return JSON.stringify(error);
+    };
+    const errorBlockStyle = {
+        padding: '8px',
+        fontSize: '20px',
+        color: 'rgb(255,255,255)',
+        backgroundColor: 'rgb(255, 0, 0)',
+    };
+    return () => createElement('div', { style: errorBlockStyle, onClick: handleClick }, formattingError());
+}
 
 class InnerAirxComponentContext {
     instance;
@@ -177,7 +180,15 @@ class InnerAirxComponentContext {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     provide(key, value) {
         this.providedMap.set(key, value);
-        return v => this.providedMap.set(key, v);
+        return v => {
+            if (typeof v === 'function') {
+                const old = this.providedMap.get(key);
+                const func = v;
+                this.providedMap.set(key, func(old));
+                return;
+            }
+            this.providedMap.set(key, v);
+        };
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     inject(key) {
@@ -372,9 +383,11 @@ function reconcileChildren(appContext, parentInstance, childrenElementArray) {
             // 添加 ref 处理
             if ('ref' in instance.memoProps) {
                 context.onMounted(() => {
-                    if (instance.domRef) { // 如果组件有自己的 dom
-                        instance.memoProps.ref.value = instance.domRef;
-                        return () => instance.memoProps.ref.value = null;
+                    const ref = instance.memoProps.ref;
+                    // 如果组件有自己的 dom 并且 ref 为 state
+                    if (instance.domRef && isState(ref)) {
+                        ref.set(instance.domRef);
+                        return () => ref.set(undefined);
                     }
                 });
             }
@@ -439,32 +452,65 @@ function performUnitOfWork(pluginContext, instance, onUpdateRequire) {
     }
     // airx 组件
     if (typeof element?.type === 'function') {
-        const collector = createCollector();
-        if (instance.render == null) {
+        if (instance.signalWatcher == null) {
+            // Watch 是惰性的，只有当 Signal 被读取时才会触发 --！
+            const signalWatcher = createWatch(async () => {
+                instance.needReRender = true;
+                onUpdateRequire?.(instance);
+                queueMicrotask(() => {
+                    signalWatcher.watch();
+                    const paddings = signalWatcher.getPending();
+                    for (const padding of paddings)
+                        padding.get();
+                });
+            });
+            instance.signalWatcher = signalWatcher;
+            instance.context.addDisposer(() => signalWatcher.unwatch());
+        }
+        if (instance.childrenRender == null) {
             const component = element.type;
-            const beforeContext = globalContext$1.current;
-            globalContext$1.current = instance.context.getSafeContext();
-            const componentReturnValue = collector.collect(() => component(instance.memoProps));
+            const beforeContext = globalContext.current;
+            globalContext.current = instance.context.getSafeContext();
+            let componentReturnValue = undefined;
+            try {
+                componentReturnValue = component(instance.memoProps);
+            }
+            catch (error) {
+                componentReturnValue = createErrorRender(error);
+            }
             if (typeof componentReturnValue !== 'function') {
-                throw new Error('Component must return a render function');
+                const error = new Error('Component must return a render function');
+                componentReturnValue = createErrorRender(error.message);
             }
-            globalContext$1.current = beforeContext;
-            instance.render = componentReturnValue;
-            const children = collector.collect(() => instance.render?.());
+            // restore context
+            globalContext.current = beforeContext;
+            instance.childrenRender = componentReturnValue;
+            const childrenComputed = createComputed(() => {
+                try {
+                    return instance.childrenRender();
+                }
+                catch (error) {
+                    return createErrorRender(error)();
+                }
+            });
+            instance.signalWatcher.watch(childrenComputed);
+            const children = childrenComputed.get();
             reconcileChildren(pluginContext, instance, childrenAsElements(children));
         }
         if (instance.needReRender) {
-            const children = collector.collect(() => instance.render?.());
+            let children;
+            try {
+                // 如果是由于父组件导致的子组件渲染
+                // 直接使用 childrenComputed.get() 将读取到缓存值
+                // 因此这里使用 childrenRender 来更新 children 的值
+                children = instance.childrenRender();
+            }
+            catch (error) {
+                children = createErrorRender(error)();
+            }
             reconcileChildren(pluginContext, instance, childrenAsElements(children));
             delete instance.needReRender;
         }
-        // 处理依赖触发的更新
-        collector.complete().forEach(ref => {
-            instance.context.addDisposer(watchSignal(ref, () => {
-                instance.needReRender = true;
-                onUpdateRequire?.(instance);
-            }));
-        });
     }
     // 浏览器组件/标签
     if (typeof element?.type === 'string') {
@@ -669,7 +715,7 @@ function render$1(pluginContext, element, onComplete) {
             Object.keys(prevProps)
                 .filter(isProperty)
                 .filter(isGone(prevProps, nextProps))
-                .forEach(name => dom.setAttribute(name, ''));
+                .forEach(name => dom.removeAttribute(name));
             // Set new or changed properties
             Object.keys(nextProps)
                 .filter(isProperty)
@@ -1137,7 +1183,7 @@ class BasicLogic {
         Object.keys(prevProps)
             .filter(isProperty)
             .filter(isGone(prevProps, nextProps))
-            .forEach(name => dom.setAttribute(name, ''));
+            .forEach(name => dom.removeAttribute(name));
         // Set new or changed properties
         Object.keys(nextProps)
             .filter(isProperty)
@@ -1190,23 +1236,30 @@ class PluginContext {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function createApp(element) {
     const appContext = new PluginContext();
+    const ensureAsElement = (element) => {
+        if (typeof element === 'function') {
+            return createElement(element, {});
+        }
+        return element;
+    };
     const app = {
         plugin: (...plugins) => {
             appContext.registerPlugin(...plugins);
             return app;
         },
         mount: (container) => {
-            render(appContext, element, container);
+            container.innerHTML = ''; // 先清空再说
+            render(appContext, ensureAsElement(element), container);
             return app;
         },
         renderToHTML: () => {
             return new Promise(resolve => {
-                render$1(appContext, element, resolve);
+                render$1(appContext, ensureAsElement(element), resolve);
             });
         }
     };
     return app;
 }
 
-export { Fragment, component, createApp, createElement, createSignal, inject, onMounted, onUnmounted, provide, watchSignal };
+export { Fragment, component, createApp, createElement, inject, onMounted, onUnmounted, provide };
 //# sourceMappingURL=index.js.map