npm - mono-jsx - Versions diffs - 0.10.0-beta.2 → 0.10.0-beta.20 - Mend

mono-jsx 0.10.0-beta.2 → 0.10.0-beta.20

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

@@ -964,8 +964,6 @@ The `<component>` element also supports the `ref` prop, which allows you to cont
 - `refresh`: A method to re-render the component with the current name and props.
 ```tsx
-import type { ComponentElement } from "mono-jsx";
 function App(this: WithRefs<FC, { component: ComponentElement }>) {
   this.effect(() => {
     // updating the component name and props will trigger a re-render of the component
@@ -1110,16 +1108,208 @@ You can access the `params` object in your route components to get the values of
 ```tsx
 // router pattern: "/post/:id"
 function Post(this: FC) {
-  this.request.url         // "http://localhost:3000/post/123"
-  this.request.params?.id  // "123"
+  console.log(this.request.url)         // "http://localhost:3000/post/123"
+  console.log(this.request.params?.id)  // "123"
+}
+```
+You can use `this.app.url` signal to get route URL and parameters:
+```tsx
+function Post(this: FC) {
+  return (
+    <div>
+      <p>Current URL: {this.$(() => this.app.url.href)}</p>
+      <p>Post id: {this.$(() => this.app.url.params?.id)}</p>
+    </div>
+  )
+}
+```
+### Using `this.app.url` Signal
+The `this.app.url` in a component is an app-level signal that contains the current route URL and parameters. It is automatically updated when the route changes, so you can use it to display the current URL in your components or control the view with `<show>`, `<hidden>` or `<switch>` elements:
+```tsx
+function App(this: FC) {
+  return (
+    <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` props 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
+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>
+  )
+}
+```
+You can also use the `navigate` method of the `<router>` element to navigate to a new route programmatically.
+```tsx
+function App(this: FC<{}, { router: RouterElement }>) {
+  return (
+    <>
+      <header>
+        <button
+          onClick={() => this.refs.router.navigate("/about", { replace: false, refresh: false })}
+        >About</button>
+      </header>
+      <router ref={this.refs.router} />
+    </>
+  )
+}
+```
+### Nav Links
+Links under the `<nav>` element will be treated as navigation links by the router. When the `href` of a nav link matches a route, an active class will be added to the link element. By default, the active class is `active`, but you can customize it by setting the `data-active-class` prop on the `<nav>` element. You can add styles for the active link using nested CSS selectors in the `style` prop of the `<nav>` element.
+```tsx
+export default {
+  fetch: (req) => (
+    <html request={req} routes={routes}>
+      <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 Route Form
+### Adding Page Metadata
-mono-jsx allows you to define a `FormHandler` function for route components to handle form data from form submissions on the current route page on the client side. To submit the form data to the `FormHandler` function, you need to set the `route` prop on the `<form>` element.
+You can add metadata to the route component by setting the `metadata` property on the route component.
-mono-jsx provides two built-in elements to allow you to control the post-submit behavior:
+```tsx
+function Home(this: FC) {
+  return <p>Home</p>
+}
+Home.metadata = {
+  title: "Home",
+  description: "Home page",
+}
+const routes = {
+  "/": Home,
+}
+```
+Or use `getMetadata` property on the route component to dynamically generate the metadata.
+```tsx
+async function Post(this: FC) {
+  const post = await getPost(this.request.params.slug)
+  return <div>
+    <h1>{post.title}</h1>
+    <h2>{post.description}</h2>
+    <div>{post.content}</div>
+  </div>
+}
+Post.getMetadata = async function(this: FC) {
+  const post = await getPost(this.request.params.slug)
+  return {
+    title: post.title,
+    description: post.description,
+  }
+}
+const routes = {
+  "/post/:slug": Post,
+}
+```
+You can define global metadata with the `metadata` prop on the root `<html>` element. It applies to every page in your app, and page-specific metadata takes precedence over these global values.
+To render metadata, add `<metadata />` inside the `head` tag:
+```tsx
+export default {
+  fetch: (req) => (
+    <html
+      request={req}
+      routes={routes}
+      metadata={{ title: "My App" }}
+    >
+      <head>
+        <metadata /> { /* <- `<title>My App<title>` will be rendered here */}
+      </head>
+      <body>
+        <rouer>
+          <p>Page not found</p>
+        </rouer>
+      </body>
+    </html>
+  )
+}
+```
+### 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.
+```tsx
+export default {
+  fetch: (req) => (
+    <html request={req} routes={routes}>
+      <router>
+        <p>Page Not Found</p>
+        <p>Back to <a href="/">Home</a></p>
+      </router>
+    </html>
+  )
+}
+```
+### Route Client Caching
+By default, the router client caches the html content from the server. To disable the caching, you can add the `dynamic` option to the route component.
+```tsx
+// Home is a static route that can be cached on the client side
+function Home(this: FC) {
+  return <p>Home</p>
+}
+// Dash is a dynamic route that will not be cached on the client side
+// it will be fetched from the server on every navigation
+function Dash(this: FC) {
+  const user = this.session.get<{ name: string }>("user")
+  return <p>Welcome back, {user?.name}!</p>
+}
+Dash.dynamic = true;
+const routes = {
+  "/": Home,
+  "/dash": Dash,
+}
+```
+## Using Route Form
+mono-jsx allows you to define a `FormHandler` function for route components to handle form data from client side form submissions. To submit the form data to the `FormHandler` function, you need to add the `route` prop to the `<form>` element.
+The `FormHandler` function is also a component, so you can use all the features of the component system in it. mono-jsx provides two built-in elements to allow you to control the post-submit behavior:
 - `<invalid for="...">{message}</invalid>` to set custom validation state for the form elements.
 - `<redirect to="..." />` to redirect to a new route/URL.
@@ -1147,19 +1337,19 @@ Login.FormHandler = function(this: FC, data: FormData) {
 const routes = {
   "/login": Login,
-  // ... other routes ...
 }
 ```
-> [!NOTE]
+> [!TIP]
 > You can use `:invalid` CSS selector to style the form elements with invalid state.
-You can also return regular HTML elements from the route form post response. The `formslot` element is used to
-mark the position where the returned HTML elements will be inserted.
+### Using `<formslot>` element
+You can return regular HTML elements from the form handler function. By default, the returned HTML is appended to the form element. Use the `<formslot>` element to control where the returned content is inserted. If any `<formslot>` element exists, the `mode` attribute on the `<form route>` element is ignored. `<formslot>` supports the following modes:
-- `<formslot mode="replaceChildren" />`: Replace the `formslot` element's children with the HTML. This is the default mode.
-- `<formslot mode="insertafter" />`: Insert HTML after the `formslot` element.
-- `<formslot mode="insertbefore" />`: Insert HTML before the `formslot` element.
+- **"replaceChildren"** (default): Replace children of the `<formslot>` element with the returned HTML.
+- **"insertafter"**: Insert HTML after the `<formslot>` element.
+- **"insertbefore"**: Insert HTML before the `<formslot>` element.
 ```tsx
 function MyRoute(this: FC) {
@@ -1182,115 +1372,103 @@ MyRoute.FormHandler = function(this: FC, data: FormData) {
 }
 ```
-You can also use the `name` prop to specify the name of the formslot element. And you can use the `formslot` prop to specify the name of the slot to insert the HTML into.
+You can add the `name` prop to specify the name of the formslot element. And use `formslot` prop in the form handler function to specify the name of the slot to insert the HTML into.
 ```tsx
 function MyRoute(this: FC) {
   return (
     <div>
-      <formslot name="message" />
       <form route>
         <button type="submit">Send</button>
+        <formslot name="info" /> { /* <- "This is info message" will be inserted here */ }
+        <formslot name="error" /> { /* <- "This is error message" will be inserted here */ }
       </form>
     </div>
   )
 }
 MyRoute.FormHandler = function(this: FC, data: FormData) {
-  return <p formslot="message">Hello, world!</p>
+  return (
+    <>
+      <p formslot="info">This is info message</p>
+      <p formslot="error">This is error message</p>
+    </>
+  )
 }
 ```
-`formslot` element accepts the `onUpdate` prop to set a callback function that will be called when the formslot element is updated.
+The `formslot` prop also accepts the following special values:
+- `:form`: Replace the form element with the returned HTML.
+- `:router`: Replace the children of current `<router>` element with the returned HTML.
+- `:root`: Replace the children of the page with the returned HTML.
 ```tsx
 function MyRoute(this: FC) {
   return (
-    <form>
-      <input type="text" name="message" placeholder="Type Message..." />
+    { /* the form will be replaced with the returned HTML after the form is submitted */ }
+    <form route>
       <button type="submit">Send</button>
-      <formslot onUpdate={(evt) => console.log("message updated:", evt.target.textContent)} />
     </form>
   )
 }
 MyRoute.FormHandler = function(this: FC, data: FormData) {
-  return <p>{data.get("message")}</p>
+  return <p formslot=":form">Form submitted</p>
 }
 ```
-The `hidden` prop can be used to hide the formslot payload from the form handler.
-```tsx
-<formslot onUpdate={(evt) => console.log("message updated:", evt.target.textContent)} hidden />
-```
-### Using `this.app.url` Signal
-`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 the view with `<show>`, `<hidden>` or `<switch>` elements:
+The `<formslot>` element accepts a `onUpdate` prop as a callback function that will be invoked when the formslot element is updated.
 ```tsx
-function App(this: FC) {
+function MyRoute(this: FC) {
   return (
-    <div>
-      <h1>Current Pathname: {this.$(() => this.app.url.pathname)}</h1>
-    </div>
+    <form>
+      <input type="text" name="message" placeholder="Type Message..." />
+      <button type="submit">Send</button>
+      <formslot hidden onUpdate={(evt) => console.log("message updated:", evt.target.textContent)} />
+    </form>
   )
 }
+MyRoute.FormHandler = function(this: FC, data: FormData) {
+  return <p>{data.get("message")}</p>
+}
 ```
-### Navigation between Pages
+> [!TIP]
+> You can use the `hidden` prop with the `onUpdate` prop to hide the formslot element. It is useful when you only want to know what content is returned from the form handler and don't want to display it on the page.
-To navigate between pages, you can use `<a>` elements with `href` props 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:
+### Submitting State
-```tsx
-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>
-  )
-}
-```
+When a `<form route>` is submitted, mono-jsx automatically manages a short "submitting" state on the client:
-### Nav Links
+- Adds a CSS class to the form while the request is in flight (default: `submitting`).
+- Disables all form controls to prevent double submit, then restores their original disabled state.
+- Clears the current content of local `<formslot>` elements before inserting the next response payload.
-Links under the `<nav>` element will be treated as navigation links by the router. When the `href` of a nav link matches a route, an active class will be added to the link element. By default, the active class is `active`, but you can customize it by setting the `data-active-class` prop on the `<nav>` element. You can add styles for the active link using nested CSS selectors in the `style` prop of the `<nav>` element.
+You can use the `data-submitting-class` attribute to customize the submitting state class name:
 ```tsx
-export default {
-  fetch: (req) => (
-    <html request={req} routes={routes}>
-      <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>
+function Contact(this: FC) {
+  return (
+    <form route data-submitting-class="is-loading">
+      <input type="email" name="email" required />
+      <button type="submit">Subscribe</button>
+      <formslot />
+    </form>
   )
 }
-```
-### 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.
+Contact.FormHandler = function(this: FC, data: FormData) {
+  return <p>Thanks, {data.get("email")}!</p>
+}
+```
-```tsx
-export default {
-  fetch: (req) => (
-    <html request={req} routes={routes}>
-      <router>
-        <p>Page Not Found</p>
-        <p>Back to <a href="/">Home</a></p>
-      </router>
-    </html>
-  )
+```css
+form.is-loading {
+  opacity: 0.6;
+  pointer-events: none;
 }
 ```
@@ -1343,17 +1521,39 @@ export default {
 ### Session Storage API
 ```ts
-function Component(this: FC) {
-  // set a value in the session
-  this.session.set("user", { name: "John" })
-  // get a value from the session
-  this.session.get<{ name: string }>("user") // { name: "John" }
-  // get all entries from the session
-  this.session.entries() // [["user", { name: "John" }]]
-  // delete a value from the session
-  this.session.delete("user")
-  // destroy the session
-  this.session.destroy()
+export interface Session {
+  /**
+   * The session ID.
+   */
+  readonly sessionId: string;
+  /**
+   * If true, update the session cookie to the client.
+   */
+  readonly isDirty: boolean;
+  /**
+   * If true, the session is expired.
+   */
+  readonly isExpired: boolean;
+  /**
+   * Gets a value from the session.
+   */
+  get<T = unknown>(key: string): T | undefined;
+  /**
+   * Gets all the entries from the session.
+   */
+  all(): Record<string, unknown>;
+  /**
+   * Sets a value in the session.
+   */
+  set(key: string, value: string | number | boolean | any[] | Record<string, unknown>): void;
+  /**
+   * Deletes a value from the session.
+   */
+  delete(key: string): void;
+  /**
+   * Destroys the session.
+   */
+  destroy(): void;
 }
 ```
@@ -1368,14 +1568,14 @@ mono-jsx provides a built-in RPC API that allows you to call functions on the se
 import { createRPC } from "mono-jsx"
 const rpc = createRPC({
-  whoami: () => ({ name: "John" })
+  whoami: () => ({ name: "John Wick" })
 })
-function App(this: FC<{ user?: { name: string } }>) {
+function App(this: FC<{ user?: { id: number, name: string } }>) {
   return (
     <div>
       <show when={this.user}>
-        <p>Welcome, {this.user!.name}!</p>
+        <p>Welcome, {this.user!.name}</p>
       </show>
       <button onClick={async () => this.user = await rpc.whoami()}>Who am I?</button>
     </div>
@@ -1402,38 +1602,27 @@ You can access the request info in RPC functions by using the `this` scope:
 - `this.context`: The [context](#using-context) object.
 - `this.session`: The [session](#session-storage-api) storage.
-```ts
-type Admin = {
-  isAdmin: (id: number) => boolean;
-}
+```tsx
 const rpc = createRPC({
-  whoami: function (this: WithContext<RPC, { admin: Admin }>) {
-    const { admin } = this.context;
-    const user =  this.session.get<{ name: string }>("user")
+  whoami: function (this: WithContext<RPC, { group: string }>) {
+    const user =  this.session.get<{ id: number, name: string }>("user")
     return {
+      ...user,
+      group: this.context.group,
       ip: this.request.headers.get("x-real-ip"),
-      isAdmin: user ? admin.isAdmin(user.id) : false,
-      user: user,
     }
   },
 })
-function App(this: FC) {
-  return (
-    <button onClick={async () => console.log(await rpc.whoami())}>Who am I?</button>
-  )
-}
 export default {
   fetch: (req) => (
     <html
       request={req}
       expose={{ rpc }}
       session={{ cookie: { secret: "..." } }}
-      context={{ admin: { isAdmin: (id: number) => id === 1 } }}
+      context={{ group: "admin" }}
     >
-      <App />
+      <button onClick={async () => console.log(await rpc.whoami())}>Who am I?</button>
     </html>
   )
 }