Add TSX documentation (#64)

Author: Perryvw

docs/advanced/language-extensions.md

@@ -6,7 +6,7 @@ import { SideBySide } from "@site/src/components/SideBySide";
 
 TypeScriptToLua provides several extensions to the TypeScript language in the form of types and helper functions. To use these language extensions, add the types to your `tsconfig.json`:
 
-```json
+```json title=tsconfig.json
 {
     "compilerOptions": {
         ...

docs/tsx.md

@@ -0,0 +1,113 @@
+---
+title: TSX
+---
+
+As of version `0.42.0`, TypeScriptToLua supports the use of TSX. To enable it, add `"jsx": "react"` to your tsconfig - other values are not supported. It is your job to make sure the required factory functions are available in the Lua environment.
+
+```json title=tsconfig.json
+{
+    "compilerOptions": {
+        ...
+        "jsx": "react",
+        ...
+    },
+}
+```
+
+TSX will be translated to lua as it would be translated to JS:
+
+```typescript
+const element = <div a={b}>Inner text!</div>;
+```
+
+Will become:
+
+```lua
+local element = React.createElement("div", {a = b}, "Inner text!");
+```
+
+## Custom factory functions
+
+It is possible to supply custom factory functions using the `jsxFactory` tsconfig setting or `/** @jsx */` annotation.
+
+### jsxFactory tsconfig example
+
+```json title=tsconfig.json
+{
+    "compilerOptions": {
+        ...
+        "jsx": "react",
+        "jsxFactory": "MyNamespace.MyCreate"
+        ...
+    },
+}
+```
+
+```typescript
+const element = <div a={b}>Inner text!</div>;
+```
+
+Will translate to:
+
+```lua
+local element = MyNamespace.MyCreate("div", {a = b}, "Inner text!");
+```
+
+### @jsx annotation example
+
+Note: the annotation MUST be at the top of the file!
+
+```typescript
+/** @jsx MyNamespace.MyCreate */
+const element = <div a={b}>Inner text!</div>;
+```
+
+Will translate to:
+
+```lua
+local element = MyNamespace.MyCreate("div", {a = b}, "Inner text!");
+```
+
+## jsxFragmentFactory
+
+You can also provide a customfragment using the `jsxFragmentFactory` tsconfig setting or `/** @jsxFrag */` annotation.
+
+### jsxFragmentFactory tsconfig example
+
+```json title=tsconfig.json
+{
+    "compilerOptions": {
+        ...
+        "jsx": "react",
+        "jsxFactory": "MyNamespace.MyCreate",
+        "jsxFragmentFactory": "MyNamespace.MyFragment"
+        ...
+    },
+}
+```
+
+```typescript
+const element = <></>;
+```
+
+Will translate to:
+
+```lua
+local element = MyNamespace.MyCreate(MyNamespace.MyFragment, {});
+```
+
+### @jsxFrag annotation example
+
+Note: the annotation MUST be at the top of the file!
+
+```typescript
+/** @jsx MyNamespace.MyCreate */
+/** @jsxFrag MyNamespace.MyCreate */
+const element = <></>;
+```
+
+Will translate to:
+
+```lua
+local element = MyNamespace.MyCreate(MyNamespace.MyFragment, {});
+```

sidebars.json

@@ -10,6 +10,7 @@
         "advanced/writing-declarations",
         "advanced/compiler-annotations",
         "advanced/language-extensions",
+        "tsx",
         {
             "type": "category",
             "label": "API",