Xterm.js Option

docs/changelog.md

@@ -7,6 +7,7 @@
 Features
 --------
 
+- Added the `xterm` attribute to `py-config`. When set to `True` or `xterm`, an (output-only) [xterm.js](http://xtermjs.org/) terminal will be used in place of the default py-terminal.
 - Added the `@when` decorator for attaching Python functions as event handlers
 - The `py-mount` attribute on HTML elements has been deprecated, and will be removed in a future release.
 

docs/reference/plugins/py-terminal.md

@@ -4,7 +4,7 @@ This is one of the core plugins in PyScript, which is active by default. With it
 
 ## Configuration
 
-You can control how `<py-terminal>` behaves by setting the value of the `terminal` configuration in your `<py-config>`, together with the `docked` one.
+You can control how `<py-terminal>` behaves by setting the values of the `terminal`, `docked`, and `xterm` fields in your configuration in your `<py-config>`.
 
 For the **terminal** field, these are the values:
 
@@ -26,6 +26,31 @@ Please note that **docked** mode is currently used as default only when `termina
 
 In all other cases it's up to the user decide if a terminal should be docked or not.
 
+For the **xterm** field, these are the values:
+
+| value | description |
+|-------|-------------|
+| `false` | This is the default. The `<py-terminal>` is a simple `<pre>` tag with some CSS styling. |
+| `true` or `xterm` | The [xtermjs](http://xtermjs.org/) library is loaded and its Terminal object is used as the `<py-terminal>`. It's visibility and position are determined by the  `docked` and `auto` keys in the same way as the default `<py-terminal>` |
+
+The xterm.js [Terminal object](http://xtermjs.org/docs/api/terminal/classes/terminal/) can be accessed directly if you want to adjust its properties, add [custom parser hooks](http://xtermjs.org/docs/guides/hooks/), introduce [xterm.js addons](http://xtermjs.org/docs/guides/using-addons/), etc. Access is best achieved by awaiting the `xtermReadyPromise` attribute of the `<py-terminal>` HTML element itself:
+
+```python
+import js
+import asyncio
+
+async def adjust_term_size(columns, rows):
+    xterm = await js.document.querySelector('py-terminal').xtermReadyPromise
+    xterm.resize(columns, rows)
+
+asyncio.ensure_future(adjust_term_size(40,10))
+```
+
+Some terminal-formatting packages read from specific environment variables to determine whether they should emit formatted output; PyScript does not set these variables explicitly - you may need to set them yourself, or force your terminal-formatting package into a state where it outputs correctly formatted output.
+
+A couple of specific examples:
+ - the [rich](https://github.com/Textualize/rich) will not, by default, output colorful text, but passing `256` or `truecolor` as an argument as the `color_system` parameter to the [Console constructor](https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console) will force it to do so. (As of rich v13)
+ - [termcolor](https://github.com/termcolor/termcolor) will not, by default, output colorful text, but setting `os.environ["FORCE_COLOR"] = "True"` or by passing `force_color=True` to the `colored()` function will force it to do so. (As of termcolor v2.3)
 
 ### Examples
 

pyscriptjs/package.json

@@ -37,7 +37,8 @@
         "pyodide": "0.22.1",
         "synclink": "0.2.4",
         "ts-jest": "29.0.3",
-        "typescript": "5.0.4"
+        "typescript": "5.0.4",
+        "xterm": "^5.1.0"
     },
     "dependencies": {
         "basic-devtools": "^0.1.6",