airx 0.4.0 → 0.7.0

package/README.md

@@ -1,118 +1,302 @@
-# 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)
+[![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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-☁️ Airx is a lightweight JSX web application framework.
+> A lightweight, Signal-driven JSX web application framework
 
-[中文文档](https://github.com/airxjs/airx/blob/main/README_CN.md)
-|
-[English Document](https://github.com/airxjs/airx/blob/main/README.md)
+[中文文档](./README_CN.md) • [English Documentation](./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.
+Airx is a modern frontend framework built on **JSX** and **Signal** primitives, designed to provide a simple, performant, and intuitive solution for building reactive web applications.
 
-## Features
+## ✨ Features
 
-- 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
+- 🔄 **Signal-driven reactivity**: Seamlessly integrates with [TC39 Signal proposal](https://github.com/tc39/proposal-signals)
+- 📝 **TypeScript-first**: Developed entirely in TypeScript with excellent type safety
+- ⚡ **Functional components**: Define components using clean JSX functional syntax
+- 🚫 **No hooks complexity**: Simple and straightforward API without React-style hooks
+- 🪶 **Lightweight**: Minimal bundle size with zero dependencies
+- 🔌 **Extensible**: Plugin system for advanced functionality
+- 🌐 **Universal**: Works in both browser and server environments
 
-## Getting Started
+## 🚀 Quick Start
 
-To begin using Airx, follow these steps:
+### Installation
 
-1. Install Airx using npm or yarn:
-
-```shell
+```bash
 npm install airx
+# or
+yarn add airx
+# or
+pnpm add airx
 ```
 
-2. Import necessary functions and components into your project:
+### Basic Usage
 
-```javascript
+```tsx
 import * as airx from 'airx'
 
-// All values based on Signal automatically trigger updates
-const state = new Signal.State(1)
-const computed = new Signal.Computed(() => state.get() + 100)
+// Create reactive state using Signal
+const count = new Signal.State(0)
+const doubleCount = new Signal.Computed(() => count.get() * 2)
 
-function App() {
-  const innerState = new Signal.State(1)
+function Counter() {
+  const localState = new Signal.State(0)
 
-  const handleClick = () => {
-    state.set(state.get() + 1)
-    innerState.set(innerState.get() + 1)
+  const increment = () => {
+    count.set(count.get() + 1)
+    localState.set(localState.get() + 1)
   }
 
-  // Return a rendering function
+  // Return a render function
   return () => (
-    <button onClick={handleClick}>
-      {state.get()}
-      {computed.get()}
-      {innerState.get()}
-    </button>
+    <div>
+      <h1>Counter App</h1>
+      <p>Global count: {count.get()}</p>
+      <p>Double count: {doubleCount.get()}</p>
+      <p>Local count: {localState.get()}</p>
+      <button onClick={increment}>
+        Click me!
+      </button>
+    </div>
   )
 }
 
-const app = airx.createApp(<App />);
-app.mount(document.getElementById('app'));
+// Create and mount the app
+const app = airx.createApp(<Counter />)
+app.mount(document.getElementById('app'))
+```
+
+## 📖 Core Concepts
+
+### Components
+
+Components in Airx are simple functions that return a render function:
+
+```tsx
+function MyComponent() {
+  const state = new Signal.State('Hello')
+  
+  return () => (
+    <div>{state.get()} World!</div>
+  )
+}
+```
+
+### State Management
+
+Airx leverages the Signal primitive for reactive state management:
+
+```tsx
+// State
+const count = new Signal.State(0)
+
+// Computed values
+const isEven = new Signal.Computed(() => count.get() % 2 === 0)
+
+// Effects
+const effect = new Signal.Effect(() => {
+  console.log('Count changed:', count.get())
+})
+```
+
+### Context & Dependency Injection
+
+```tsx
+const ThemeContext = Symbol('theme')
+
+function App() {
+  // Provide values down the component tree
+  airx.provide(ThemeContext, 'dark')
+  
+  return () => <Child />
+}
+
+function Child() {
+  // Inject values from parent components
+  const theme = airx.inject(ThemeContext)
+  
+  return () => (
+    <div className={`theme-${theme}`}>
+      Current theme: {theme}
+    </div>
+  )
+}
 ```
 
-## API
+### Lifecycle Hooks
+
+```tsx
+function Component() {
+  airx.onMounted(() => {
+    console.log('Component mounted')
+    
+    // Return cleanup function
+    return () => {
+      console.log('Component unmounted')
+    }
+  })
+
+  airx.onUnmounted(() => {
+    console.log('Component will unmount')
+  })
+  
+  return () => <div>My Component</div>
+}
 
-We have only a few APIs because we pursue a minimal core design. In the future, we will also open up a plugin system.
+## 📚 API Reference
 
-### createApp
+Airx follows a minimal API design philosophy. Here are the core APIs:
 
-Create an application instance.
+### `createApp(element)`
 
-### provide
+Creates an application instance.
 
-```ts
-function provide: <T = unknown>(key: unknown, value: T): ProvideUpdater<T>
+```tsx
+const app = airx.createApp(<App />)
+app.mount(document.getElementById('root'))
 ```
 
-Inject a value downwards through the `context`, must be called synchronously directly or indirectly within a component.
+### `provide<T>(key, value): ProvideUpdater<T>`
 
-### inject
+Provides a value down the component tree through context. Must be called synchronously within a component.
 
-```ts
-function inject<T = unknown>(key: unknown): T | undefined
+```tsx
+function Parent() {
+  airx.provide('theme', 'dark')
+  return () => <Child />
+}
 ```
 
-Look up a specified value upwards through the `context`, must be called synchronously directly or indirectly within a component.
+### `inject<T>(key): T | undefined`
 
-### onMounted
+Retrieves a provided value from the component tree. Must be called synchronously within a component.
 
-```ts
+```tsx
+function Child() {
+  const theme = airx.inject('theme')
+  return () => <div>Theme: {theme}</div>
+}
+```
+
+### `onMounted(listener): void`
+
+Registers a callback for when the component is mounted to the DOM.
+
+```tsx
 type MountedListener = () => (() => void) | void
-function onMounted(listener: MountedListener): void
+
+airx.onMounted(() => {
+  console.log('Mounted!')
+  return () => console.log('Cleanup')
+})
 ```
 
-Register a callback for when the DOM is mounted, must be called synchronously directly or indirectly within a component.
+### `onUnmounted(listener): void`
 
-### onUnmounted
+Registers a callback for when the component is unmounted from the DOM.
 
-```ts
+```tsx
 type UnmountedListener = () => void
-function onUnmounted(listener: UnmountedListener): void
+
+airx.onUnmounted(() => {
+  console.log('Unmounted!')
+})
+```
+
+### `createElement(type, props, ...children)`
+
+Creates virtual DOM elements (usually handled by JSX transpiler).
+
+### `Fragment`
+
+A component for grouping multiple elements without adding extra DOM nodes.
+
+```tsx
+function App() {
+  return () => (
+    <airx.Fragment>
+      <div>First</div>
+      <div>Second</div>
+    </airx.Fragment>
+  )
+}
 ```
 
-Register a callback for when the DOM is unmounted, must be called synchronously directly or indirectly within a component.
+## 🔧 Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/airxjs/airx.git
+cd airx
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with UI
+npm run test:ui
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Project Structure
+
+```text
+source/
+├── app/           # Application creation and management
+├── element/       # Virtual DOM and JSX handling
+├── logger/        # Internal logging utilities
+├── render/        # Rendering engine
+│   ├── basic/     # Core rendering logic
+│   ├── browser/   # Browser-specific rendering
+│   └── server/    # Server-side rendering
+├── signal/        # Signal integration
+├── symbol/        # Internal symbols
+└── types/         # TypeScript type definitions
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Ensure all tests pass (`npm test`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
 
-## License
+## 📄 License
 
-This project uses the MIT License. For detailed information, please refer to the [LICENSE](LICENSE) file.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-## Contribution
+## 🙏 Acknowledgments
 
-Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.
+- Thanks to all contributors and supporters of the Airx project
+- Inspired by the [TC39 Signal proposal](https://github.com/tc39/proposal-signals)
+- Built with ❤️ by the Airx community
 
-## Acknowledgements
+## 📞 Support
 
-We want to thank all contributors and supporters of the Airx project.
+- 📖 [Documentation](https://github.com/airxjs/airx)
+- 🐛 [Issue Tracker](https://github.com/airxjs/airx/issues)
+- 💬 [Discussions](https://github.com/airxjs/airx/discussions)
 
 ---
 
-For more information, please refer to the [official documentation](https://github.com/airxjs/airx)
+Made with ☁️ by the Airx team

package/output/app/app.d.ts

@@ -0,0 +1,11 @@
+import { Plugin } from '../render';
+import { AirxComponent, AirxElement } from '../element';
+export interface AirxApp {
+    mount: (container: HTMLElement) => AirxApp;
+    /** @deprecated WIP */
+    plugin: (...plugins: Plugin[]) => AirxApp;
+    /** @deprecated WIP */
+    renderToHTML: () => Promise<string>;
+}
+export declare function createApp(element: AirxElement<any> | AirxComponent): AirxApp;
+//# sourceMappingURL=app.d.ts.map

package/output/app/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../source/app/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,MAAM,EAAiB,MAAM,WAAW,CAAA;AAC9E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAA;AAEtE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,CAAC,SAAS,EAAE,WAAW,KAAK,OAAO,CAAA;IAE1C,sBAAsB;IACtB,MAAM,EAAE,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAA;IACzC,sBAAsB;IACtB,YAAY,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CACpC;AAGD,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,aAAa,GAAG,OAAO,CA+B5E"}

package/output/app/app.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=app.test.d.ts.map

package/output/app/app.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.test.d.ts","sourceRoot":"","sources":["../../source/app/app.test.ts"],"names":[],"mappings":""}

package/output/app/index.d.ts

@@ -0,0 +1,2 @@
+export * from './app';
+//# sourceMappingURL=index.d.ts.map

package/output/app/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAA"}

package/output/{esm → element}/element.d.ts

@@ -1,4 +1,4 @@
-import * as symbol from './symbol';
+import * as symbol from '../symbol';
 type AirxElementType<P> = string | AirxComponent<P>;
 export type Props = {
     [propKey: string]: unknown;
@@ -46,3 +46,4 @@ export type AirxComponentContext = AirxComponentLifecycle & {
 export declare function component<P = unknown>(comp: AirxComponent<P>): AirxComponent<P>;
 export declare function createErrorRender(error: unknown): AirxComponentRender;
 export {};
+//# sourceMappingURL=element.d.ts.map

package/output/element/element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../../source/element/element.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,WAAW,CAAA;AAGnC,KAAK,eAAe,CAAC,CAAC,IAAI,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;AAEnD,MAAM,MAAM,KAAK,GAAG;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAA;AAElD;;;;;;GAMG;AAEH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,GAAG;IAClC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;IACxB,KAAK,EAAE,KAAK,GAAG,CAAC,CAAA;IAChB,CAAC,MAAM,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAA;CACjC;AAED,MAAM,MAAM,YAAY,GACpB,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,GACP,SAAS,GACT,WAAW,GACX,KAAK,CAAC,YAAY,CAAC,GACnB,mBAAmB,CAAA;AAEvB;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,YAAY,CAAA;AACpD,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAA;AAC7D,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,mBAAmB,CAAA;AAE9E;;GAEG;AAEH,wBAAgB,aAAa,CAAC,CAAC,GAAG,GAAG,EACnC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,EACxB,KAAK,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,CAAC,EACrC,GAAG,QAAQ,EAAE,YAAY,EAAE,GAC1B,WAAW,CAAC,CAAC,CAAC,CAiBhB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,WAAW,CAIvE;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE;IAAE,QAAQ,EAAE,WAAW,CAAA;CAAE,0BAExD;AAED,MAAM,MAAM,8BAA8B,GAAG,MAAM,IAAI,CAAA;AACvD,MAAM,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;AAEpE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,CAAC,QAAQ,EAAE,4BAA4B,KAAK,IAAI,CAAA;IAC3D,WAAW,EAAE,CAAC,QAAQ,EAAE,8BAA8B,KAAK,IAAI,CAAA;CAChE;AAED,KAAK,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAA;AAE1E,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,GAAG;IAC1D,OAAO,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC,CAAA;IACnE,MAAM,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,CAAC,GAAG,SAAS,CAAA;CACrD,CAAA;AAED,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAE/E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAwBrE"}

package/output/element/element.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=element.test.d.ts.map

package/output/element/element.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.test.d.ts","sourceRoot":"","sources":["../../source/element/element.test.ts"],"names":[],"mappings":""}

package/output/element/index.d.ts

@@ -0,0 +1,2 @@
+export { Props, AirxElement, AirxComponent, AirxChildren, createElement, AirxComponentRender, ReactiveComponent, Fragment, component, AirxComponentContext, isValidElement, AirxComponentMountedListener, AirxComponentUnmountedListener, createErrorRender } from './element';
+//# sourceMappingURL=index.d.ts.map

package/output/element/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/element/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,oBAAoB,EACpB,cAAc,EACd,4BAA4B,EAC5B,8BAA8B,EAC9B,iBAAiB,EAClB,MAAM,WAAW,CAAA"}

package/output/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export { type Plugin } from './render';
+export { type AirxApp, createApp } from './app';
+export { Fragment, component, createElement, type AirxComponent, type AirxElement, type AirxChildren, type AirxComponentContext } from './element';
+export { inject, provide, onMounted, onUnmounted } from './render';
+//# sourceMappingURL=index.d.ts.map

package/output/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,EAAE,KAAK,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAE/C,OAAO,EACL,QAAQ,EACR,SAAS,EACT,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EAC1B,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,MAAM,EACN,OAAO,EACP,SAAS,EACT,WAAW,EACZ,MAAM,UAAU,CAAA"}