npm - mono-jsx - Versions diffs - 0.3.4 → 0.5.0 - Mend

mono-jsx 0.3.4 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -6,8 +6,8 @@ mono-jsx is a JSX runtime that renders `<html>` element to `Response` object in
 - 🚀 No build step needed
 - 🦋 Lightweight (8KB gzipped), zero dependencies
-- 🔫 Minimal state runtime
-- 🚨 Complete Web API TypeScript definitions
+- 🚦 Signals as reactive primitives
+- 🗂️ Complete Web API TypeScript definitions
 - ⏳ Streaming rendering
 - 🥷 [htmx](#using-htmx) integration
 - 🌎 Universal, works in Node.js, Deno, Bun, Cloudflare Workers, etc.
@@ -72,8 +72,8 @@ export default {
     <html>
       <h1>Welcome to mono-jsx!</h1>
     </html>
-  ),
-};
+  )
+}
 ```
 For Deno/Bun users, you can run the `app.tsx` directly:
@@ -173,7 +173,7 @@ function Container() {
       {/* Named slot */}
       <slot name="desc" />
     </div>
-  );
+  )
 }
 function App() {
@@ -184,7 +184,7 @@ function App() {
       {/* This goes to the default slot */}
       <h1>Hello world!</h1>
     </Container>
-  );
+  )
 }
 ```
@@ -207,7 +207,7 @@ function App() {
       <style>{css`h1 { font-size: 3rem; }`}</style>
       <script>{js`console.log("Hello world!")`}</script>
     </head>
-  );
+  )
 }
 ```
@@ -224,7 +224,7 @@ function Button() {
     <button onClick={(evt) => alert("BOOM!")}>
       Click Me
     </button>
-  );
+  )
 }
 ```
@@ -234,9 +234,10 @@ function Button() {
 ```tsx
 import { doSomething } from "some-library";
-function Button(this: FC, props: { role: string }) {
-  let message = "BOOM!";
-  console.log(message); // only executes on server-side
+function Button(this: FC<{ count: 0 }>, props: { role: string }) {
+  const message = "BOOM!";        // server-side variable
+  this.count = 0;                 // initialize a signal
+  console.log(message);           // only prints on server-side
   return (
     <button
       role={props.role}
@@ -247,137 +248,230 @@ function Button(this: FC, props: { role: string }) {
         Deno.exit(0);             // ❌ `Deno` is unavailable in the browser
         document.title = "BOOM!"; // ✅ `document` is a browser API
         console.log(evt.target);  // ✅ `evt` is the event object
-        this.count++;             // ✅ update the state `count`
+        this.count++;             // ✅ update the `count` signal
       }}
     >
-      Click Me
+      <slot />
     </button>
-  );
+  )
 }
 ```
-Additionally, mono-jsx supports the `mount` event for when elements are mounted in the client-side DOM:
+### Using `<form>` Element
-```jsx
-function App() {
-  return (
-    <div onMount={(evt) => console.log(evt.target, "Mounted!")}>
-      <h1>Welcome to mono-jsx!</h1>
-    </div>
-  );
-}
-```
-mono-jsx also accepts functions for the `action` property on `form` elements, which will be called on form submission:
+mono-jsx supports `<form>` elements with the `action` attribute. The `action` attribute can be a string URL or a function that accepts a `FormData` object. The function will be called on form submission, and the `FormData` object will contain the form data.
 ```tsx
 function App() {
   return (
-    <form action={(data: FormData, event: SubmitEvent) => console.log(data.get("name"))}>
+    <form action={(data: FormData) => console.log(data.get("name"))}>
       <input type="text" name="name" />
       <button type="submit">Submit</button>
     </form>
-  );
+  )
+}
+```
+## Async Components
+mono-jsx supports async components that return a `Promise` or an async function. With [streaming rendering](#streaming-rendering), async components are rendered asynchronously, allowing you to fetch data or perform other async operations before rendering the component.
+```tsx
+async function Loader(props: { url: string }) {
+  const data = await fetch(url).then((res) => res.json());
+  return <JsonViewer data={data} />;
+}
+export default {
+  fetch: (req) => (
+    <html>
+      <Loader url="https://api.example.com/data" placeholder={<p>Loading...</p>} />
+    </html>
+  )
+}
+```
+You can also use async generators to yield multiple elements over time. This is useful for streaming rendering of LLM tokens:
+```jsx
+async function* Chat(props: { prompt: string }) {
+  const stream = await openai.chat.completions.create({
+    model: "gpt-4",
+    messages: [{ role: "user", content: prompt }],
+    stream: true,
+  });
+  for await (const event of stream) {
+    const text = event.choices[0]?.delta.content;
+    if (text) {
+      yield <span>{text}</span>;
+    }
+  }
+}
+export default {
+  fetch: (req) => (
+    <html>
+      <Chat prompt="Tell me a story" placeholder={<span style="color:grey">●</span>} />
+    </html>
+  )
 }
 ```
-## Reactive
+## Using Signals
-mono-jsx provides a minimal state runtime for updating the view based on client-side state changes.
+mono-jsx uses signals for updating the view when a signal changes. Signals are similar to React's state, but they are more lightweight and efficient. You can use signals to manage state in your components.
-### Using Component State
+### Using Component Signals
-You can use the `this` keyword in your components to manage state. The state is bound to the component instance and can be updated directly, and will automatically re-render the view when the state changes:
+You can use the `this` keyword in your components to manage signals. The signals is bound to the component instance and can be updated directly, and will automatically re-render the view when a signal changes:
 ```tsx
 function Counter(
   this: FC<{ count: number }>,
   props: { initialCount?: number },
 ) {
-  // Initialize state
+  // Initialize a singal
   this.count = props.initialCount ?? 0;
   return (
     <div>
-      {/* render state */}
+      {/* render singal */}
       <span>{this.count}</span>
-      {/* Update state to trigger re-render */}
+      {/* Update singal to trigger re-render */}
       <button onClick={() => this.count--}>-</button>
       <button onClick={() => this.count++}>+</button>
     </div>
-  );
+  )
 }
 ```
-### Using App State
+### Using App Signals
-You can define app state by adding `appState` prop to the root `<html>` element. The app state is available in all components via `this.app.<stateKey>`. Changes to the app state will trigger re-renders in all components that use it:
+You can define app signals by adding `app` prop to the root `<html>` element. The app signals is available in all components via `this.app.<SignalName>`. Changes to the app signals will trigger re-renders in all components that use it:
 ```tsx
-function Header(this: FC<{}, { title: string }>) {
+interface AppSignals {
+  themeColor: string;
+}
+function Header(this: FC<{}, AppSignals>) {
   return (
     <header>
-      <h1>{this.app.title}</h1>
+      <h1 style={this.computed(() => ({ color: this.app.themeColor }))}>Welcome to mono-jsx!</h1>
     </header>
-  );
+  )
 }
-function Footer(this: FC<{}, { title: string }>) {
+function Footer(this: FC<{}, AppSignals>) {
   return (
     <footer>
-      <p>(c) 2025 {this.app.title}</p>
+      <p style={this.computed(() => ({ color: this.app.themeColor }))}>(c) 2025 mono-jsx.</p>
     </footer>
-  );
+  )
 }
-function Main(this: FC<{}, { title: string }>) {
+function Main(this: FC<{}, AppSignals>) {
   return (
     <main>
-      <h1>{this.app.title}</h1>
-      <h2>Changing the title</h2>
-      <input
-        onInput={(evt) => this.app.title = evt.target.value}
-        placeholder="Enter a new title"
-      />
+      <p>
+        <label>Theme Color: </label>
+        <input type="color" onInput={({ target }) => this.app.themeColor = target.value}/>
+      </p>
     </main>
-  );
+  )
 }
 export default {
   fetch: (req) => (
-    <html appState={{ title: "Welcome to mono-jsx!" }}>
+    <html app={{ themeColor: "#232323" }}>
       <Header />
       <Main />
       <Footer />
     </html>
-  ),
-};
+  )
+}
 ```
-### Using Computed State
+### Using Computed Signals
-You can use `this.computed` to create computed state based on state. The computed state will automatically update when the state changes:
+You can use `this.computed` to create a derived signal based on other signals:
 ```tsx
 function App(this: FC<{ input: string }>) {
-  this.input = "Welcome to mono-jsx!";
+  this.input = "Welcome to mono-jsx";
   return (
     <div>
       <h1>{this.computed(() => this.input + "!")}</h1>
       <form action={(fd) => this.input = fd.get("input") as string}>
-        <input type="text" name="input" value={this.input} />
+        <input type="text" name="input" value={"" + this.input} />
         <button type="submit">Submit</button>
       </form>
     </div>
-  );
+  )
+}
+```
+### Using Effects
+You can use `this.effect` to create side effects based on signals. The effect will run whenever the signal changes:
+```tsx
+function App(this: FC<{ count: number }>) {
+  this.count = 0;
+  this.effect(() => {
+    console.log("Count changed:", this.count);
+  });
+  return (
+    <div>
+      <span>{this.count}</span>
+      <button onClick={() => this.count++}>+</button>
+    </div>
+  )
+}
+```
+The callback function of `this.effect` can return a cleanup function that gets run once the component element has been removed via `<toggle>` or `<switch>` condition rendering:
+```tsx
+function Counter(this: FC<{ count: number }>) {
+  this.count = 0;
+  this.effect(() => {
+    const interval = setInterval(() => {
+      this.count++;
+    }, 1000);
+    return () => clearInterval(interval);
+  });
+  return (
+    <div>
+      <span>{this.count}</span>
+    </div>
+  )
+}
+function App(this: FC<{ show: boolean }>) {
+  this.show = true
+  return (
+    <div>
+      <toggle show={this.show}>
+        <Foo />
+      </toggle>
+      <button onClick={e => this.show = !this.show }>{this.computed(() => this.show ? 'Hide': 'Show')}</button>
+    </div>
+  )
 }
 ```
-### Using `<toggle>` Element with State
+### Using `<toggle>` Element with Signals
-The `<toggle>` element conditionally renders content based on the value of a state.
+The `<toggle>` element conditionally renders content based on the `show` prop:
 ```tsx
 function App(this: FC<{ show: boolean }>) {
@@ -389,7 +483,7 @@ function App(this: FC<{ show: boolean }>) {
   return (
     <div>
-      <toggle value={this.show}>
+      <toggle show={this.show}>
         <h1>Welcome to mono-jsx!</h1>
       </toggle>
@@ -397,16 +491,16 @@ function App(this: FC<{ show: boolean }>) {
         {this.computed(() => this.show ? "Hide" : "Show")}
       </button>
     </div>
-  );
+  )
 }
 ```
-### Using `<switch>` Element with State
+### Using `<switch>` Element with Signals
-The `<switch>` element renders different content based on the value of a state. Elements with matching `slot` attributes are displayed when their value matches, otherwise default content is shown:
+The `<switch>` element renders different content based on the value of a signal. Elements with matching `slot` attributes are displayed when their value matches, otherwise default slots are shown:
 ```tsx
-function App(this: FC<{ lang: "en" | "zh" | "emoji" }>) {
+function App(this: FC<{ lang: "en" | "zh" | "🙂" }>) {
   this.lang = "en";
   return (
@@ -419,19 +513,19 @@ function App(this: FC<{ lang: "en" | "zh" | "emoji" }>) {
       <p>
         <button onClick={() => this.lang = "en"}>English</button>
         <button onClick={() => this.lang = "zh"}>中文</button>
-        <button onClick={() => this.lang = "emoji"}>Emoji</button>
+        <button onClick={() => this.lang = "🙂"}>🙂</button>
       </p>
     </div>
-  );
+  )
 }
 ```
-### Limitation of State
+### Limitation of Signals
-1\. Component state cannot be used in arrow function components.
+1\. Arrow function are non-stateful components.
 ```tsx
-// ❌ Won't work - state updates won't refresh the view
+// ❌ Won't work - use `this` in a non-stateful component
 const App = () => {
   this.count = 0;
   return (
@@ -439,7 +533,7 @@ const App = () => {
       <span>{this.count}</span>
       <button onClick={() => this.count++}>+</button>
     </div>
-  );
+  )
 };
 // ✅ Works correctly
@@ -450,16 +544,16 @@ function App(this: FC) {
       <span>{this.count}</span>
       <button onClick={() => this.count++}>+</button>
     </div>
-  );
+  )
 }
 ```
-2\. Component state cannot be computed outside of the `this.computed` method.
+2\. Signals cannot be computed outside of the `this.computed` method.
 ```tsx
-// ❌ Won't work - state updates won't refresh the view
+// ❌ Won't work - updates of a signal won't refresh the view
 function App(this: FC<{ message: string }>) {
-  this.message = "Welcome to mono-jsx!";
+  this.message = "Welcome to mono-jsx";
   return (
     <div>
       <h1 title={this.message + "!"}>{this.message + "!"}</h1>
@@ -467,12 +561,12 @@ function App(this: FC<{ message: string }>) {
         Click Me
       </button>
     </div>
-  );
+  )
 }
 // ✅ Works correctly
 function App(this: FC) {
-  this.message = "Welcome to mono-jsx!";
+  this.message = "Welcome to mono-jsx";
   return (
     <div>
       <h1 title={this.computed(() => this.message + "!")}>{this.computed(() => this.message + "!")}</h1>
@@ -480,33 +574,89 @@ function App(this: FC) {
         Click Me
       </button>
     </div>
-  );
+  )
+}
+```
+3\. The callback function of `this.computed` must be a pure function. That means it should not create side effects or access any non-stateful variables. For example, you cannot use `Deno` or `document` in the callback function:
+```tsx
+// ❌ Won't work - throws `Deno is not defined` when the button is clicked
+function App(this: FC<{ message: string }>) {
+  this.message = "Welcome to mono-jsx";
+  return (
+    <div>
+      <h1>{this.computed(() => this.message + "! (Deno " + Deno.version.deno + ")")}</h1>
+      <button onClick={() => this.message = "Clicked"}>
+        Click Me
+      </button>
+    </div>
+  )
+}
+// ✅ Works correctly
+function App(this: FC<{ message: string, denoVersion: string }>) {
+  this.denoVersion = Deno.version.deno;
+  this.message = "Welcome to mono-jsx";
+  return (
+    <div>
+      <h1>{this.computed(() => this.message + "! (Deno " + this.denoVersion + ")")}</h1>
+      <button onClick={() => this.message = "Clicked"}>
+        Click Me
+      </button>
+    </div>
+  )
 }
 ```
 ## Using `this` in Components
-mono-jsx binds a special `this` object to your components when they are rendered. This object contains properties and methods that you can use to manage state, context, and other features.
+mono-jsx binds a scoped signals object to `this` of your component functions. This allows you to access signals, context, and request information directly in your components.
-The `this` object contains the following properties:
+The `this` object has the following built-in properties:
-- `app`: The app state defined on the root `<html>` element.
+- `app`: The app signals defined on the root `<html>` element.
 - `context`: The context defined on the root `<html>` element.
 - `request`: The request object from the `fetch` handler.
-- `computed`: A method to create computed properties based on state.
+- `refs`: A map of refs defined in the component.
+- `computed`: A method to create a computed signal.
+- `effect`: A method to create side effects.
 ```ts
-type FC<State = {}, AppState = {}, Context = {}> = {
-  readonly app: AppState;
+type FC<Signals = {}, AppSignals = {}, Context = {}> = {
+  readonly app: AppSignals;
   readonly context: Context;
   readonly request: Request;
-  readonly computed: <V = unknown>(computeFn: () => V) => V;
-} & Omit<State, "app" | "context" | "request" | "computed">;
+  readonly refs: Record<string, HTMLElement | null>;
+  readonly computed: <T = unknown>(fn: () => T) => T;
+  readonly effect: (fn: () => void | (() => void)) => void;
+} & Omit<Signals, "app" | "context" | "request" | "computed" | "effect">;
 ```
-### Using State
+### Using Signals
+See the [Using Signals](#using-signals) section for more details on how to use signals in your components.
+### Using Refs
-Check the [Using State](#using-state) section for more details on how to use state in your components.
+You can use `this.refs` to access refs in your components. Define refs in your component using the `ref` attribute:
+```tsx
+function App(this: FC) {
+  this.effect(() => {
+    this.refs.input?.addEventListener("input", (evt) => {
+      console.log("Input changed:", evt.target.value);
+    });
+  });
+  return (
+    <div>
+      <input ref={this.refs.input} type="text" />
+      <button onClick={() => this.refs.input?.focus()}>Focus</button>
+    </div>
+  )
+}
+```
 ### Using Context
@@ -520,7 +670,7 @@ function Dash(this: FC<{}, {}, { auth: { uuid: string; name: string } }>) {
       <h1>Welcome back, {auth.name}!</h1>
       <p>Your UUID is {auth.uuid}</p>
     </div>
-  );
+  )
 }
 export default {
@@ -531,9 +681,9 @@ export default {
         {!auth && <p>Please Login</p>}
         {auth && <Dash />}
       </html>
-    );
-  },
-};
+    )
+  }
+}
 ```
 ### Accessing Request Info
@@ -550,7 +700,7 @@ function RequestInfo(this: FC) {
       <p>{request.url}</p>
       <p>{request.headers.get("user-agent")}</p>
     </div>
-  );
+  )
 }
 export default {
@@ -558,8 +708,8 @@ export default {
     <html request={req}>
       <RequestInfo />
     </html>
-  ),
-};
+  )
+}
 ```
 ## Streaming Rendering
@@ -575,38 +725,29 @@ async function Sleep({ ms }) {
 export default {
   fetch: (req) => (
     <html>
-      <h1>Welcome to mono-jsx!</h1>
-      <Sleep ms={1000} placeholder={<p>Sleeping...</p>}>
+      <Sleep ms={1000} placeholder={<p>Loading...</p>}>
         <p>After 1 second</p>
       </Sleep>
     </html>
-  ),
-};
+  )
+}
 ```
 You can set the `rendering` attribute to `"eager"` to force synchronous rendering (the `placeholder` will be ignored):
 ```jsx
-async function Sleep({ ms }) {
-  await new Promise((resolve) => setTimeout(resolve, ms));
-  return <slot />;
-}
 export default {
   fetch: (req) => (
     <html>
-      <h1>Welcome to mono-jsx!</h1>
       <Sleep ms={1000} rendering="eager">
         <p>After 1 second</p>
       </Sleep>
     </html>
-  ),
-};
+  )
+}
 ```
-You can add the `catch` attribute to handle errors in async components. The `catch` attribute should be a function that returns a JSX element:
+You can add the `catch` attribute to handle errors in the async component. The `catch` attribute should be a function that returns a JSX element:
 ```jsx
 async function Hello() {
@@ -617,15 +758,15 @@ async function Hello() {
 export default {
   fetch: (req) => (
     <html>
-      <Hello catch={err => <p>{err.messaage}</p>} />
+      <Hello catch={err => <p>{err.message}</p>} />
     </html>
-  ),
-};
+  )
+}
 ```
 ## Customizing html Response
-Add `status` or `headers` attributes to the root `<html>` element to customize the response:
+You can add `status` or `headers` attributes to the root `<html>` element to customize the http response:
 ```jsx
 export default {
@@ -635,12 +776,13 @@ export default {
       headers={{
         cacheControl: "public, max-age=0, must-revalidate",
         setCookie: "name=value",
+        "x-foo": "bar",
       }}
     >
       <h1>Page Not Found</h1>
     </html>
-  ),
-};
+  )
+}
 ```
 ### Using htmx
@@ -666,9 +808,9 @@ export default {
           Click Me
         </button>
       </html>
-    );
-  },
-};
+    )
+  }
+}
 ```
 #### Adding htmx Extensions
@@ -683,8 +825,8 @@ export default {
         Click Me
       </button>
     </html>
-  ),
-};
+  )
+}
 ```
 #### Specifying htmx Version
@@ -699,8 +841,8 @@ export default {
         Click Me
       </button>
     </html>
-  ),
-};
+  )
+}
 ```
 #### Installing htmx Manually
@@ -721,8 +863,8 @@ export default {
         </button>
       </body>
     </html>
-  ),
-};
+  )
+}
 ```
 ## License