npm - mono-jsx - Versions diffs - 0.6.6 → 0.6.8 - Mend

mono-jsx 0.6.6 → 0.6.8

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 (10) hide show

package/README.md CHANGED Viewed

@@ -14,6 +14,8 @@ mono-jsx is a JSX runtime that renders `<html>` element to `Response` object in
 - 🥷 [htmx](#using-htmx) integration
 - 🌎 Universal, works in Node.js, Deno, Bun, Cloudflare Workers, etc.
+Playground: https://val.town/x/ije/mono-jsx
 ## Installation
 mono-jsx supports all modern JavaScript runtimes including Node.js, Deno, Bun, and Cloudflare Workers.
@@ -30,7 +32,7 @@ deno add npm:mono-jsx
 bun add mono-jsx
 ```
-## Setup JSX Runtime
+### Setup JSX Runtime
 To use mono-jsx as your JSX runtime, add the following configuration to your `tsconfig.json` (or `deno.json` for Deno):
@@ -43,12 +45,6 @@ To use mono-jsx as your JSX runtime, add the following configuration to your `ts
 }
 ```
-Alternatively, you can use a pragma directive in your JSX file:
-```js
-/** @jsxImportSource mono-jsx */
-```
 You can also run `mono-jsx setup` to automatically add the configuration to your project:
 ```bash
@@ -62,6 +58,18 @@ deno run -A npm:mono-jsx setup
 bunx mono-jsx setup
 ```
+### Zero Configuration
+Alternatively, you can use `@jsxImportSource` pragma directive without installation mono-jsx(no package.json/tsconfig/node_modules), the runtime(deno/bun) automatically installs mono-jsx to your computer:
+```js
+// Deno, Valtown
+/** @jsxImportSource https://esm.sh/mono-jsx */
+// Bun
+/** @jsxImportSource mono-jsx */
+```
 ## Usage
 mono-jsx allows you to return an `<html>` JSX element as a `Response` object in the `fetch` handler:
@@ -82,7 +90,7 @@ For Deno/Bun users, you can run the `app.tsx` directly:
 ```bash
 deno serve app.tsx
-bun run app.tsx
+bun app.tsx
 ```
 If you're building a web app with [Cloudflare Workers](https://developers.cloudflare.com/workers/wrangler/commands/#dev), use `wrangler dev` to start your app in development mode:
@@ -150,11 +158,13 @@ mono-jsx supports [pseudo classes](https://developer.mozilla.org/en-US/docs/Web/
 ```tsx
 <a
   style={{
+    display: "inline-flex",
+    gap: "0.5em",
     color: "black",
     "::after": { content: "↩️" },
     ":hover": { textDecoration: "underline" },
     "@media (prefers-color-scheme: dark)": { color: "white" },
-    "& .icon": { width: "1em", height: "1em", marginRight: "0.5em" },
+    "& .icon": { width: "1em", height: "1em" },
   }}
 >
   <img class="icon" src="link.png" />
@@ -192,7 +202,7 @@ function App() {
 ### Using `html` Tag Function
-mono-jsx provides an `html` tag function to render raw HTML in JSX instead of React's `dangerouslySetInnerHTML`:
+mono-jsx provides an `html` tag function to render raw HTML in JSX instead of React's `dangerouslySetInnerHTML` property.
 ```tsx
 function App() {
@@ -200,7 +210,7 @@ function App() {
 }
 ```
-The `html` tag function is globally available without importing. You can also use `css` and `js` tag functions for CSS and JavaScript:
+The `html` function is globally available without importing. You can also use `css` and `js` functions for CSS and JavaScript:
 ```tsx
 function App() {
@@ -230,8 +240,7 @@ function Button() {
 }
 ```
-> [!NOTE]
-> Event handlers are never called on the server-side. They're serialized to strings and sent to the client. **This means you should NOT use server-side variables or functions in event handlers.**
+Event handlers are never called on the server-side. They're serialized to strings and sent to the client. **This means you should NOT use server-side variables or functions in event handlers.**
 ```tsx
 import { doSomething } from "some-library";
@@ -361,7 +370,7 @@ interface AppSignals {
 function Header(this: FC<{}, AppSignals>) {
   return (
     <header>
-      <h1 style={this.computed(() => ({ color: this.app.themeColor }))}>Welcome to mono-jsx!</h1>
+      <h1 style={{ color: this.app.themeColor }}>Welcome to mono-jsx!</h1>
     </header>
   )
 }
@@ -369,7 +378,7 @@ function Header(this: FC<{}, AppSignals>) {
 function Footer(this: FC<{}, AppSignals>) {
   return (
     <footer>
-      <p style={this.computed(() => ({ color: this.app.themeColor }))}>(c) 2025 mono-jsx.</p>
+      <p style={{ color: this.app.themeColor }}>(c) 2025 mono-jsx.</p>
     </footer>
   )
 }
@@ -416,6 +425,9 @@ function App(this: FC<{ input: string }>) {
 }
 ```
+> [!TIP]
+> You can use `this.$` as a shorthand for `this.computed` to create computed signals.
 ### Using Effects
 You can use `this.effect` to create side effects based on signals. The effect will run whenever the signal changes:
@@ -473,7 +485,7 @@ function App(this: FC<{ show: boolean }>) {
 ### Using `<toggle>` Element with Signals
-The `<toggle>` element conditionally renders content based on the `show` prop:
+The `<toggle>` element conditionally renders content based on the `show` prop. You can use signals to control the visibility of the content on the client side.
 ```tsx
 function App(this: FC<{ show: boolean }>) {
@@ -499,7 +511,7 @@ function App(this: FC<{ show: boolean }>) {
 ### Using `<switch>` Element with Signals
-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:
+The `<switch>` element renders different content based on the `value` prop. Elements with matching `slot` attributes are displayed when their value matches, otherwise default slots are shown. Like `<toggle>`, you can use signals to control the value on the client side.
 ```tsx
 function App(this: FC<{ lang: "en" | "zh" | "🙂" }>) {
@@ -617,7 +629,7 @@ mono-jsx binds a scoped signals object to `this` of your component functions. Th
 The `this` object has the following built-in properties:
-- `app`: The app signals defined on the root `<html>` element.
+- `app`: The app global signals..
 - `context`: The context defined on the root `<html>` element.
 - `request`: The request object from the `fetch` handler.
 - `refs`: A map of refs defined in the component.
@@ -625,12 +637,13 @@ The `this` object has the following built-in properties:
 - `effect`: A method to create side effects.
 ```ts
-type FC<Signals = {}, AppSignals = {}, Context = {}> = {
-  readonly app: AppSignals;
+type FC<Signals = {}, AppSignals = {}, Context = {}, Refs = {}, AppRefs = {}> = {
+  readonly app: AppSignals & { refs: AppRefs; url: WithParams<URL> }
   readonly context: Context;
-  readonly request: Request & { params?: Record<string, string> };
-  readonly refs: Record<string, HTMLElement | null>;
+  readonly request: WithParams<Request>;
+  readonly refs: Refs;
   readonly computed: <T = unknown>(fn: () => T) => T;
+  readonly $: FC["computed"];
   readonly effect: (fn: () => void | (() => void)) => void;
 } & Omit<Signals, "app" | "context" | "request" | "computed" | "effect">;
 ```
@@ -641,10 +654,10 @@ See the [Using Signals](#using-signals) section for more details on how to use s
 ### Using Refs
-You can use `this.refs` to access refs in your components. Define refs in your component using the `ref` attribute:
+You can use `this.refs` to access refs in your components. Refs are defined using the `ref` attribute in JSX, and they allow you to access DOM elements directly. The `refs` object is a map of ref names to DOM elements.
 ```tsx
-function App(this: FC) {
+function App(this: Refs<FC, { input: HTMLInputElement }>) {
   this.effect(() => {
     this.refs.input?.addEventListener("input", (evt) => {
       console.log("Input changed:", evt.target.value);
@@ -660,12 +673,55 @@ function App(this: FC) {
 }
 ```
+You can also use `this.app.refs` to access app-level refs:
+```tsx
+function Layout(this: Refs<FC, {}, { h1: HTMLH1Element }>) {
+  return (
+    <>
+    <header>
+      <h1 ref={this.refs.h1}>Welcome to mono-jsx!</h1>
+    </header>
+    <main>
+      <slot />
+    </main>
+    </>
+  )
+}
+```
+Element `<componet>` also support `ref` attribute, which allows you to control the component rendering manually. The `ref` will be a `ComponentElement` that has the `name`, `props`, and `refresh` properties:
+- `name`: The name of the component to render.
+- `props`: The props to pass to the component.
+- `refresh`: A method to re-render the component with the current name and props.
+```tsx
+function App(this: Refs<FC, { component: ComponentElement }>) {
+  this.effect(() => {
+    // updating the component name and props will trigger a re-render of the component
+    this.refs.component.name = "Foo";
+    this.refs.component.props = {};
+    const timer = setInterval(() => {
+       // re-render the component
+      this.refs.component.refresh();
+    }, 1000);
+    return () => clearInterval(timer); // cleanup
+  });
+  return (
+    <div>
+      <component ref={this.refs.component} />
+    </div>
+  )
+}
 ### Using Context
 You can use the `context` property in `this` to access context values in your components. The context is defined on the root `<html>` element:
 ```tsx
-function Dash(this: FC<{}, {}, { auth: { uuid: string; name: string } }>) {
+function Dash(this: Context<FC, { auth: { uuid: string; name: string } }>) {
   const { auth } = this.context;
   return (
     <div>
@@ -788,7 +844,7 @@ async function Lazy(this: FC<{ show: boolean }>, props: { url: string }) {
   this.show = false;
   return (
     <div>
-      <toggle value={this.show}>
+      <toggle show={this.show}>
         <component name="Foo" props={{ /* props for the component */ }} placeholder={<p>Loading...</p>} />
       </toggle>
      <button onClick={() => this.show = true }>Load `Foo` Component</button>
@@ -836,7 +892,7 @@ export default {
 }
 ```
-## Using Router(SPA)
+## Using Router(SPA Mode)
 mono-jsx provides a built-in `<router>` element that allows your app to render components based on the current URL. On client side, it listens all `click` events on `<a>` elements and asynchronously fetches the route component without reloading the entire page.
@@ -853,13 +909,11 @@ const routes = {
 export default {
   fetch: (req) => (
     <html request={req} routes={routes}>
-      <header>
-        <nav>
-          <a href="/">Home</a>
-          <a href="/about">About</a>
-          <a href="/blog">Blog</a>
-        </nav>
-      </header>
+      <nav>
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+        <a href="/blog">Blog</a>
+      </nav>
       <router />
     </html>
   )
@@ -872,12 +926,10 @@ mono-jsx router requires [URLPattern](https://developer.mozilla.org/en-US/docs/W
 - ✅ Cloudflare Workers
 - ✅ Nodejs (>= 24)
-For Bun users, mono-jsx provides a `monoRoutes` function that uses Bun's built-in routing:
+For Bun users, mono-jsx provides a `buildRoutes` function that uses Bun's built-in server routing:
 ```tsx
-// bun app.tsx
-import { monoRoutes } from "mono-jsx"
+import { buildRoutes } from "mono-jsx"
 const routes = {
   "/": Home,
@@ -886,13 +938,18 @@ const routes = {
   "/post/:id": Post,
 }
-export default {
-  routes: monoRoutes(routes, (request) => (
-    <html request={request}>
+Bun.serve({
+  routes: buildRoutes((req) => (
+    <html request={req} routes={routes}>
+      <nav>
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+        <a href="/blog">Blog</a>
+      </nav>
       <router />
     </html>
   ))
-}
+})
 ```
 ### Using Route `params`
@@ -909,18 +966,36 @@ function Post(this: FC) {
 }
 ```
-### Using DB/Storage in Route Components
+### Using `this.app.url` Signal
-Route components are always rendered on server-side, you can use any database or storage API to fetch data in your route components.
+`this.app.url` is an app-level signal that contains the current route url and parameters. The `this.app.url` signal is automatically updated when the route changes, so you can use it to display the current URL in your components, or control view with `<toggle>` or `<switch>` elements:
 ```tsx
-async function Post(this: FC) {
-  const post = await sql`SELECT * FROM posts WHERE id = ${ this.request.params!.id }`
+function App(this: FC) {
   return (
-    <article>
-      <h2>{post.title}<h2>
-      <div>html`${post.content}`</div>
-    </article>
+    <div>
+      <h1>Current Pathname: {this.$(() => this.app.url.pathname)}</h1>
+    </div>
+  )
+}
+```
+### Navigation between Pages
+To navigate between pages, you can use `<a>` elements with `href` attributes that match the defined routes. The router will intercept the click events of these links and fetch the corresponding route component without reloading the page:
+```tsx
+function App() {
+  export default {
+  fetch: (req) => (
+    <html request={req} routes={routes}>
+      <nav>
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+        <a href="/blog">Blog</a>
+      </nav>
+      <router />
+    </html>
   )
 }
 ```
@@ -933,19 +1008,35 @@ Links under the `<nav>` element will be treated as navigation links by the route
 export default {
   fetch: (req) => (
     <html request={req} routes={routes}>
-      <header>
-        <nav style={{ "& a.active": { fontWeight: "bold" } }} data-active-class="active">
-          <a href="/">Home</a>
-          <a href="/about">About</a>
-          <a href="/blog">Blog</a>
-        </nav>
-      </header>
+      <nav style={{ "& a.active": { fontWeight: "bold" } }} data-active-class="active">
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+        <a href="/blog">Blog</a>
+      </nav>
       <router />
     </html>
   )
 }
 ```
+### Using DB/Storage in Route Components
+Route components are always rendered on server-side, you can use any database or storage API to fetch data in your route components.
+```tsx
+async function Post(this: FC) {
+  const post = await sql`SELECT * FROM posts WHERE id = ${ this.request.params!.id }`
+  return (
+    <article>
+      <h2>{post.title}<h2>
+      <section>
+        {html(post.content)}
+      </section>
+    </article>
+  )
+}
+```
 ### Fallback(404)
 You can add fallback(404) content to the `<router>` element as children, which will be displayed when no route matches the current URL.

package/index.mjs CHANGED Viewed

@@ -1,4 +1,8 @@
 // index.ts
+function buildRoutes(handler) {
+  const { routes = {} } = handler(Symbol.for("mono.setup"));
+  return monoRoutes(routes, handler);
+}
 function monoRoutes(routes, handler) {
   const handlers = {};
   for (const [path, fc] of Object.entries(routes)) {
@@ -10,5 +14,6 @@ function monoRoutes(routes, handler) {
   return handlers;
 }
 export {
+  buildRoutes,
   monoRoutes
 };