ajo 0.1.11 → 0.1.12

package/dist/html.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const{entries:$,hasOwn:g}=Object,m=e=>typeof e!="string"&&typeof(e==null?void 0:e[Symbol.iterator])=="function",y=e=>[...u(e)].join(""),u=function*(e){for(e of f(e))if(typeof e=="string")yield p(e);else{const{nodeName:t,key:r,skip:l,memo:n,ref:a,children:o,...c}=e;let i="";for(const[s,d]of $(c))s.startsWith("set:")||d==null||d===!1||(i+=d===!0?`${i} ${s}`:`${i} ${s}="${p(String(d))}"`);v.has(t)?yield`<${t}${i}>`:l?yield`<${t}${i}></${t}>`:typeof o=="string"?yield`<${t}${i}>${o}</${t}>`:(yield`<${t}${i}>`,yield*u(o),yield`</${t}>`)}},f=function*(e,t={value:""},r=!0){for(e of m(e)?e:[e])if(!(e==null||typeof e=="boolean"))if(g(e,"nodeName")){const{value:l}=t,{nodeName:n}=e,a=typeof n;if(l&&(yield l,t.value=""),a==="function")if(n.constructor.name==="GeneratorFunction"){const o={},c={};for(const[i,s]of $(e))i!=="is"&&(i==="children"?c.children=s:i.startsWith("arg:")?c[i.slice(4)]=s:o[i]=s);o.nodeName=e.is??n.is??"div",o.children=k(n,c),yield o}else delete e.nodeName,yield*f(n(e),t,!1);else a==="string"&&(yield e)}else m(e)?yield*f(e,t,!1):t.value+=e;r&&t.value&&(yield t.value)},v=new Set("area,base,br,col,command,embed,hr,img,input,keygen,link,meta,param,source,track,wbr".split(",")),p=e=>e.replace(/[&<>"']/g,t=>`&#${t.charCodeAt(0)};`),k=(e,t)=>{let r,l;try{const n=e.call(r={$args:t,*[Symbol.iterator](){for(;;)yield t},refresh(){},next(){l=y(n.next().value)},throw(a){l=y(n.throw(a).value)},return(){n.return()}},t);r.next()}catch(n){r.throw(n)}finally{r.return()}return l};exports.html=u;exports.render=y;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const{entries:p,hasOwn:$}=Object,u=e=>typeof e!="string"&&typeof(e==null?void 0:e[Symbol.iterator])=="function",d=e=>[...f(e)].join(""),f=function*(e){for(e of y(e))if(typeof e=="string")yield m(e);else{const{nodeName:t,skip:r,children:i=""}=e;let n="";for(const[l,o]of p(e))k.has(l)||l.startsWith("set:")||o==null||o===!1||(n+=o===!0?`${n} ${l}`:`${n} ${l}="${m(String(o))}"`);g.has(t)?yield`<${t}${n}>`:r?yield`<${t}${n}></${t}>`:typeof i=="string"?yield`<${t}${n}>${i}</${t}>`:(yield`<${t}${n}>`,yield*f(i),yield`</${t}>`)}},y=function*(e,t={value:""},r=!0){for(e of u(e)?e:[e])if(!(e==null||typeof e=="boolean"))if($(e,"nodeName")){const{value:i}=t,{nodeName:n}=e,l=typeof n;if(i&&(yield i,t.value=""),l==="function")if(n.constructor.name==="GeneratorFunction"){const o={},a={};for(const[s,c]of p(e))s==="children"?a.children=c:s.startsWith("arg:")?a[s.slice(4)]=c:o[s]=c;o.nodeName=n.is??"div",o.children=v(n,a),yield o}else delete e.nodeName,yield*y(n(e),t,!1);else l==="string"&&(yield e)}else u(e)?yield*y(e,t,!1):t.value+=e;r&&t.value&&(yield t.value)},g=new Set("area,base,br,col,command,embed,hr,img,input,keygen,link,meta,param,source,track,wbr".split(",")),k=new Set("nodeName,key,skip,memo,ref,children".split(",")),m=e=>e.replace(/[&<>"']/g,t=>`&#${t.charCodeAt(0)};`),v=(e,t)=>{let r,i;try{const n=e.call(r={$args:t,*[Symbol.iterator](){for(;;)yield t},refresh(){},next(){i=d(n.next().value)},throw(l){i=d(n.throw(l).value)},return(){n.return()}},t);r.next()}catch(n){r.throw(n)}finally{r.return()}return i};exports.html=f;exports.render=d;

package/dist/html.js

@@ -1,34 +1,34 @@
-const { entries: p, hasOwn: g } = Object, f = (e) => typeof e != "string" && typeof (e == null ? void 0 : e[Symbol.iterator]) == "function", u = (e) => [...$(e)].join(""), $ = function* (e) {
-  for (e of y(e))
+const { entries: m, hasOwn: $ } = Object, y = (e) => typeof e != "string" && typeof (e == null ? void 0 : e[Symbol.iterator]) == "function", f = (e) => [...p(e)].join(""), p = function* (e) {
+  for (e of d(e))
     if (typeof e == "string")
-      yield m(e);
+      yield u(e);
     else {
-      const { nodeName: t, key: r, skip: l, memo: n, ref: a, children: o, ...c } = e;
-      let i = "";
-      for (const [s, d] of p(c))
-        s.startsWith("set:") || d == null || d === !1 || (i += d === !0 ? `${i} ${s}` : `${i} ${s}="${m(String(d))}"`);
-      k.has(t) ? yield `<${t}${i}>` : l ? yield `<${t}${i}></${t}>` : typeof o == "string" ? yield `<${t}${i}>${o}</${t}>` : (yield `<${t}${i}>`, yield* $(o), yield `</${t}>`);
+      const { nodeName: t, skip: r, children: i = "" } = e;
+      let n = "";
+      for (const [l, o] of m(e))
+        k.has(l) || l.startsWith("set:") || o == null || o === !1 || (n += o === !0 ? `${n} ${l}` : `${n} ${l}="${u(String(o))}"`);
+      g.has(t) ? yield `<${t}${n}>` : r ? yield `<${t}${n}></${t}>` : typeof i == "string" ? yield `<${t}${n}>${i}</${t}>` : (yield `<${t}${n}>`, yield* p(i), yield `</${t}>`);
     }
-}, y = function* (e, t = { value: "" }, r = !0) {
-  for (e of f(e) ? e : [e])
+}, d = function* (e, t = { value: "" }, r = !0) {
+  for (e of y(e) ? e : [e])
     if (!(e == null || typeof e == "boolean"))
-      if (g(e, "nodeName")) {
-        const { value: l } = t, { nodeName: n } = e, a = typeof n;
-        if (l && (yield l, t.value = ""), a === "function")
+      if ($(e, "nodeName")) {
+        const { value: i } = t, { nodeName: n } = e, l = typeof n;
+        if (i && (yield i, t.value = ""), l === "function")
           if (n.constructor.name === "GeneratorFunction") {
-            const o = {}, c = {};
-            for (const [i, s] of p(e))
-              i !== "is" && (i === "children" ? c.children = s : i.startsWith("arg:") ? c[i.slice(4)] = s : o[i] = s);
-            o.nodeName = e.is ?? n.is ?? "div", o.children = v(n, c), yield o;
+            const o = {}, a = {};
+            for (const [s, c] of m(e))
+              s === "children" ? a.children = c : s.startsWith("arg:") ? a[s.slice(4)] = c : o[s] = c;
+            o.nodeName = n.is ?? "div", o.children = w(n, a), yield o;
           } else
-            delete e.nodeName, yield* y(n(e), t, !1);
+            delete e.nodeName, yield* d(n(e), t, !1);
         else
-          a === "string" && (yield e);
+          l === "string" && (yield e);
       } else
-        f(e) ? yield* y(e, t, !1) : t.value += e;
+        y(e) ? yield* d(e, t, !1) : t.value += e;
   r && t.value && (yield t.value);
-}, k = new Set("area,base,br,col,command,embed,hr,img,input,keygen,link,meta,param,source,track,wbr".split(",")), m = (e) => e.replace(/[&<>"']/g, (t) => `&#${t.charCodeAt(0)};`), v = (e, t) => {
-  let r, l;
+}, g = new Set("area,base,br,col,command,embed,hr,img,input,keygen,link,meta,param,source,track,wbr".split(",")), k = new Set("nodeName,key,skip,memo,ref,children".split(",")), u = (e) => e.replace(/[&<>"']/g, (t) => `&#${t.charCodeAt(0)};`), w = (e, t) => {
+  let r, i;
   try {
     const n = e.call(r = {
       $args: t,
@@ -39,10 +39,10 @@ const { entries: p, hasOwn: g } = Object, f = (e) => typeof e != "string" && typ
       refresh() {
       },
       next() {
-        l = u(n.next().value);
+        i = f(n.next().value);
       },
-      throw(a) {
-        l = u(n.throw(a).value);
+      throw(l) {
+        i = f(n.throw(l).value);
       },
       return() {
         n.return();
@@ -54,9 +54,9 @@ const { entries: p, hasOwn: g } = Object, f = (e) => typeof e != "string" && typ
   } finally {
     r.return();
   }
-  return l;
+  return i;
 };
 export {
-  $ as html,
-  u as render
+  p as html,
+  f as render
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ajo",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "ajo is a JavaScript view library for building user interfaces",
   "type": "module",
   "module": "./dist/index.js",

package/readme.md

@@ -265,7 +265,7 @@ In Ajo, there are several special attributes (`key`, `skip`, `memo`, and `ref`)
 - **Behavior:** When an element is mounted or updated, the `ref` callback is called with the DOM element as an argument. This allows you to store a reference to it for later use, such as focusing an input or measuring dimensions.
 - **Example:** `h('input', { ref: el => (this.inputNode = el) })` - stores a reference to the input element.
 
-## Stateful components
+## Stateful Components
 
 Stateful components in Ajo are defined using generator functions. These components are designed with a minimalistic API for controlling rendering and state updates. They are equipped with several lifecycle methods that allow for advanced control over component behavior, error handling, and rendering processes.
 
@@ -349,6 +349,40 @@ function* ChatComponent({ user = 'Anonymous', room }) { // Receive arguments ini
 }
 ```
 
+### Default Rendering Behavior
+
+By default, when a stateful component is rendered in Ajo, it wraps its yielded content within a `<div>` element. This `<div>` becomes the context of the component's generator function, referred to as `this` within the function. 
+
+For example:
+
+```javascript
+function* MyComponent() {
+  // The 'this' variable here refers to the default 'div' wrapper element
+}
+```
+> This default behavior ensures a consistent and predictable wrapper for your component's content, making it easier to manage and style.
+
+### Customizing the Wrapper Element
+
+While the default wrapper is a `<div>`, Ajo provides the flexibility to change this to any other HTML element type. This is particularly useful for semantic correctness or when integrating with existing HTML structures, especially in SSR scenarios.
+
+To specify a different element type for the wrapper, set the `is` property on the Generator Function of your component. For example:
+
+```javascript
+function* MyCustomRow() {
+  // The 'this' variable here refers to the default 'tr' wrapper element
+}
+
+MyCustomRow.is = 'tr'
+```
+> This code will instruct Ajo to render a `<tr>` element instead of the default `<div>`. This capability is crucial for rendering and hydrating any type of HTML element when using stateful components.
+
+#### SSR and Hydration
+
+In the context of Server-Side Rendering (SSR), this feature allows Ajo to gracefully hydrate existing SSR-generated DOM elements. It means that Ajo can extend the functionality of built-in browser DOM elements without relying on Web Components or standards like Declarative Shadow DOM.
+
+This approach provides a streamlined, efficient method for enhancing and manipulating built-in elements, offering a more practical solution compared to the complexities of Web Components.
+
 ## Lifecycle methods
 
 Stateful components in Ajo are equipped with several methods that allow for advanced control over component behavior, error handling, and rendering processes. These methods are called lifecycle methods and are invoked at different stages of the component's lifecycle.
@@ -580,6 +614,115 @@ function* ChildComponent({ data, onEvent }) {
 
 This `arg:` prefixed attribute system in Ajo enhances the clarity and readability of component composition. It makes the intent of passing down arguments more explicit, reducing confusion between HTML attributes, and other special properties. This is especially beneficial in complex applications where components have multiple responsibilities and interact with both their children and the DOM.
 
+## Server-Side Rendering (SSR)
+
+Ajo supports Server-Side Rendering (SSR), enabling components to be rendered to HTML in server-side JavaScript environments. This feature enhances the capabilities of Ajo for projects requiring SEO-friendly pages and faster initial page loads.
+
+### SSR Implementation with `ajo/html`
+
+For SSR in Ajo, use the `render` and `html` functions from the `ajo/html` module. These functions are designed to convert a virtual DOM tree into an HTML string or HTML chunks for streaming, suitable for server-side environments.
+
+### Client-Side Hydration
+
+Once HTML is rendered on the server, it can be hydrated on the client-side by Ajo to become interactive. The client-side `render` function can render into the root element containing the SSR-generated DOM.
+
+### Example Usage
+
+Server-side:
+
+```javascript
+import express from 'express'
+import { render } from 'ajo/html'
+import { App } from './components'
+
+const app = express()
+
+app.get('/', (req, res) => {
+
+  const html = render(<App />)
+
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>My App</title>
+      </head>
+      <body>
+        <div id="root">${html}</div>
+      </body>
+    </html>`)
+})
+
+app.listen(3000)
+```
+
+Client-side:
+
+```javascript
+import { render } from 'ajo'
+import { App } from './components'
+
+// Hydrate the #root element with the server-rendered DOM
+render(<App />, document.getElementById('root'))
+```
+
+### Streaming HTML Chunks
+
+The `html` function is designed to be used with various streaming technologies. Its output can be seamlessly integrated into different streaming environments, offering developers the flexibility to choose the streaming solution that best fits their project requirements.
+
+This streaming capability is useful for progressively rendering content, enhancing Time to First Paint (TTFP) and user experience. It allows browsers to begin rendering content as soon as the initial chunks arrive.
+
+## SSR API
+
+### `render(h: Any): String`
+
+Renders a virtual DOM tree (`h`) into a complete HTML string.
+
+#### Parameters:
+
+- **h** (Any): The virtual DOM tree to render. This can be any value, a simple string, or a virtual DOM tree created by the `h` function.
+
+#### Returns:
+
+- A string representation of the rendered HTML.
+
+#### Example Usage:
+
+```javascript
+import { render } from 'ajo/html'
+import { App } from './components'
+
+const html = render(<App />)
+// The `html` can be sent as part of an HTTP response
+```
+
+### `html(h: Any): Generator`
+
+A generator function that iterates through a virtual DOM tree, yielding HTML strings.
+
+#### Parameters:
+
+- **h** (Any): The virtual DOM tree to iterate through.
+
+#### Yield:
+
+- Yields HTML strings corresponding to each node in the virtual DOM.
+
+#### Usage:
+
+- Suitable for streaming HTML chunks to the client, compatible with any streaming technology.
+
+#### Example Usage:
+
+```javascript
+import { html } from 'ajo/html'
+import { App } from './components'
+
+for (const chunk of html(<App />)) {
+  stream.push(chunk)
+}
+```
+
 ## Acknowledgments
 Ajo takes heavy inspiration from [Incremental DOM](https://github.com/google/incremental-dom) and [Crank.js](https://github.com/bikeshaving/crank)