docs: jsx

Author: wibus-wee

docs/.vitepress/config.ts

@@ -54,6 +54,15 @@ export default defineConfig({
             link: '/components/lifecycle',
           },],
         },
+        {
+          text: 'Describing the UI', items: [{
+            text: 'JSX',
+            link: '/jsx/overview',
+          }, {
+            text: 'Writing JSX',
+            link: '/jsx/writing-jsx',
+          }]
+        }
       ]
     },
 

docs/jsx/overview.md

@@ -0,0 +1,38 @@
+# Overview
+
+JSX is a syntax extension to JavaScript. It was developed by Facebook to improve the development experience of writing JavaScript code for React applications. It is similar to a template language, but it has full power of JavaScript.
+
+::: warning
+You might think that HTML is very similar to JSX, but the key difference is that JSX has full power of JavaScript. Also, JSX syntax is different from HTML syntax, so you can't just drop JSX into a HTML file and expect it to work.
+
+You can see how to convert HTML to JSX in the [Converting HTML to JSX](./writing-jsx.md#converting-html-to-jsx) section of the [Writing JSX](./writing-jsx.md) page. It also describes how to convert JSX back to HTML.
+:::
+
+JSX is not a requirement for using React, but it is a common way to describe what the UI should look like. JSX may remind you of a template language, but it comes with the full power of JavaScript.
+
+## JSX Demo
+
+JSX is not a separate programming language, but rather a syntax extension for JavaScript. This means that you can use JSX within your JavaScript code, just like you would use any other JavaScript expression.
+
+JSX uses angle brackets (`< >`) to enclose HTML-like tags, which can contain attributes and children. For example, you can use JSX to create a simple component like this:
+
+```js
+const element = <h1>Hello, world!</h1>;
+```
+
+JSX tags may contain children:
+
+```js
+const element = (
+  <h1 className="greeting">
+    Hello, world!
+  </h1>
+);
+```
+
+JSX tags may contain expressions:
+
+```js
+const name = 'Josh Perez';
+const element = <h1>Hello, {name}</h1>;
+```

docs/jsx/writing-jsx.md

@@ -0,0 +1,109 @@
+# Writing JSX
+
+## Converting HTML to JSX
+
+Here is an example of how you might convert a simple HTML file to JSX:
+
+```html
+<div class="container">
+  <h1>Hello World!</h1>
+  <h2>Good to see you here.</h2>
+  <img src="https://example.com/favicon.ico" alt="Logo" >
+</div>
+```
+
+If you put it into JSX, it would create a error. JSX tags must have a closing tag, and the `<img>` tag doesn't have a closing tag. So you need to add a closing tag to the `<img>` tag.
+
+So the JSX version of the above HTML would be:
+
+```js
+<div className="container">
+  <h1>Hello World!</h1>
+  <h2>Good to see you here.</h2>
+  <img src="https://example.com/favicon.ico" alt="Logo" /> // [!code focus]
+</div>
+```
+
+## Rules of JSX
+
+### Must return a single element
+
+JSX must have a single root element. If you want to return multiple elements, you need to wrap them in a single element.
+
+Here is a wrong example:
+
+```js
+const element = (
+  <h1>Hello!</h1>
+  <h2>Good to see you here.</h2>
+);
+```
+
+Here is a correct example:
+
+```js
+const element = (
+  <div>
+    <h1>Hello!</h1>
+    <h2>Good to see you here.</h2>
+  </div>
+);
+```
+
+### Don't want to add a wrapper element？
+
+If you don't want to add a wrapper element, you can use Fragment to wrap multiple elements.
+
+```js
+const element = (
+  <>
+    <h1>Hello!</h1>
+    <h2>Good to see you here.</h2>
+  </>
+);
+```
+
+`<>` is a shorthand for `Fragment`. It is a common pattern to use Fragment to wrap multiple elements. It is also a good practice to use Fragment when you don't want to add a wrapper element.
+
+```js
+const element = (
+  <Fragment>
+    <h1>Hello!</h1>
+    <h2>Good to see you here.</h2>
+  </Fragment>
+);
+```
+
+### Must be closed
+
+JSX tags must be closed. If you don't want to add a child element, you can use self-closing tag.
+
+```js 
+<div>
+  <h1>Hello!</h1>
+  <br /> // [!code focus]
+  <h2>Good to see you here.</h2>
+  <hr />  // [!code focus]
+  <img src="https://example.com/favicon.ico" alt="Logo" />  // [!code focus]
+</div>
+```
+
+### camelCase all HTML attributes (except `class` )
+
+JSX in jwc.js is different from usual JSX. We have changed some attributes to the original attribute name.
+
+::: warning
+Because jwc.js still in `alpha` status, we may change the attribute name in the future.
+:::
+
+1. camelCase all most of the **event** names. For example, `onclick` becomes `onClick`.
+
+```js
+<button onClick={handleClick}>Click me</button>
+```
+
+2. `class` remains the same <Badge text="Pending" type="warning" />. It's different from React, which uses `className`.
+
+```js
+<div class="container"></div>
+```