# XRshell apps & components

<img src='https://codeberg.org/xrsh/xrsh/media/branch/main/xrsh.svg' width="25%"/>

This is a library of useful AFRAME components used in [XRSH](https://xrsh.isvery.ninja) [or in any AFRAME app].<br>
Characteristics:

* selfcontained 
* auto-loading of dependencies (via [AFRAME.utils.require()](com/require.js) see this [example](com/example/helloworld.js))

# Usage

```html
<script src="https://codeberg.org/xrsh/xrsh-com/com/require.js"/>
<script src="https://codeberg.org/xrsh/xrsh-com/com/example/helloworld.js"/>

<a-entity helloworld="foo:1" class="cubes" name="box">  
```

See component list below

> this README.md is generated by running `echo "$(./README.awk com/*.js)" > README.md`

## Credits

This project is partially funded through [NGI0 Entrust](https://nlnet.nl/entrust), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/xrsh).

[<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
[<img src="https://nlnet.nl/image/logos/NGI0_tag.svg" alt="NGI Zero Logo" width="20%" />](https://nlnet.nl/entrust)

# Component List


## [data_events](com/data_events.js)

allows components to react to data changes 

```html 
 <script>
   AFRAME.registerComponent('mycom',{
     init: function(){ this.data.foo = 1 }, 
     event: {
       foo:   (e) => alert("I was updated!")
     }
   })
 </script>

 <a-entity mycom data_events/>
```



## [html-as-texture-in-xr](com/html-as-texture-in-xr.js)

shows domid **only** in immersive mode 
(wrapper around [aframe-htmlmesh](https://ada.is/aframe-htmlmesh/)

It also sets class 'XR' to the (HTML) body-element in immersive mode.
This allows CSS (in [dom component](com/dom.js)) to visually update accordingly.

> depends on [AFRAME.utils.require](com/require.js)

```html 
 <style type="text/css">
   .XR #foo { color:red; }
 </style>

 <a-entity html-as-texture-in-xr="domid: #foo">
   <b id="foo">hello</b>
 </a-entitiy>
```

| property     | type               |
|--------------|--------------------|
| `domid`      | `string`           |

| event        | target     | info                                 |
|--------------|------------|--------------------------------------|
| `3D`         | a-scene    | fired when going into immersive mode |
| `2D`         | a-scene    | fired when leaving immersive mode    |



## [isoterminal](com/isoterminal.js)

Renders a windowed terminal in both (non)immersive mode.
It displays an interactive javascript console or boots into 
a Linux ISO image (via WASM).

```html 
  <a-entity isoterminal="iso: xrsh.iso" position="0 1.6 -0.3"></a-entity>
```

> depends on [AFRAME.utils.require](com/require.js)

| property          | type      | default                | info |
|-------------------|-----------|------------------------|------|
| `iso`             | `string`  | https`//forgejo.isvery.ninja/assets/xrsh-buildroot/main/xrsh.iso" | |
| `overlayfs`       | `string`  | ''     | zip URL/file to autoextract on top of filesystem |
| `width`           | `number`  |  800   ||
| `height`          | `number`  |  600   ||
| `depth`           | `number`  |  0.03  ||
| `lineHeight`      | `number`  |  18    ||
| `bootMenu`        | `string`  |  ""    | character to auto-enter in bootMenu  |
| `bootMenuURL`     | `string`  |  ""    | character to auto-enter in bootMenu when URL has fragment (#foo.zip e.g.) |
| `padding`         | `number`  |  18    | |
| `maximized`       | `boolean` | false  | |
| `minimized`       | `boolean` | false  | |
| `muteUntilPrompt` | `boolean` | true   | mute stdout until a prompt is detected in ISO |
| `HUD`             | `boolean` | false  | link to camera movement |
| `transparent`     | `boolean` | false  | heavy, needs good gpu |
| `memory`          | `number`  | 60     | VM memory (in MB) [NOTE` quest or smartphone webworker might crash > 40mb ] |
| `bufferLatency`   | `number`  | 1      | in ms` bufferlatency from webworker to term (batch-update every char to texture) |
| `debug`           | `boolean` | false  | |
| `emulator`        | `string`  | fbterm | terminal emulator |

> for more info see [xrsh.isvery.ninja](https://xrsh.isvery.ninja)

Component design:
```
                  css/html template                                                                                
                                                                                                                    
                    ┌─────────┐   ┌────────────┐                  exit-AR                                
           ┌───────►│ com/dom ┼──►│ com/window ├───────────────── exit-VR  ◄─┐                           
           │        └─────────┘   └───────────┬┘                             │                           
           │                                  │                              │                           
┌──────────┴────────┐                         │   ┌───────────┐    ┌─────────────────────────────┐
│  com/isoterminal  ├────────────────────────────►│com/term.js│    │com/html-as-texture-in-XR.js │
└────────┬─┬────────┘                         │   └──┬─────┬▲─┘    └─────────────────────────────┘
         │ │        ┌────────┐             ┌──▼──────▼──────┐                     ││        │                       
         │ └───────►│ plane  ├─────►text───┼►div#isoterminal│◄────────────────── enter-VR   │                       
         │          └────────┘             └────────────────┘                    enter-AR ◄─┘                       
         │                                   │                                                     
         │                                   │                                                                   
         │                             ISOTerminal.js                                                                   
         │                ┌───────────────────────────┐           
         │                │ com/isoterminal/worker.js ├            
         │                └──────────────┌────────────┤            
         │                     │         │ v86.js     │            
         │                     │         │ feat/*.js  │            
         │                     │         │ libv86.js  │            
         │                     │         └────────────┘            
         │                     │         
         └─────────────────────┘    
                                                                                                                    
NOTE: For convenience reasons, events are forwarded between com/isoterminal.js, worker.js and ISOTerminal
      Instead of a melting pot of different functionnames, events are flowing through everything (ISOTerminal.emit())
```       


## [launcher](com/launcher.js)

displays app (icons) in 2D and 3D handmenu (enduser can launch desktop-like 'apps')

```html
<a-entity launcher>
  <a-entity launch="component: helloworld; foo: bar"><a-entity>
</a-entity>
 
```

| property     | type               | example                                                                                |
|--------------|--------------------|----------------------------------------------------------------------------------------|
| `attach`     | `selector`         | hand or object to attach menu to                                                       |
| `registries` | `array` of strings | `<a-entity launcher="registers: https://foo.com/index.json, ./index.json"/>`           |

| event        | target | info                                                                                               |
|--------------|-------------------------------------------------------------------------------------------------------------|
| `launcher`   | an app | when pressing an app icon, `launcher` event will be send to the respective app                     |

There a multiple ways of letting the launcher know that an app can be launched:

1. any AFRAME component with an `launcher`-event + manifest is automatically added:
 
 ```javascript
 AFRAME.registerComponent('foo',{
   events:{
     launcher: function(){ ...launch something... }
   },
   manifest:{ // HTML5 manifesto JSON object
     // https://www.w3.org/TR/appmanifest/ 
   }
 }
 ```

2. dynamically in javascript   

```javascript
window.launcher.register({
  name:"foo",
  icon: "https://.../optional_icon.png" 
  description: "lorem ipsum",
  cb: () => alert("foo")
})
//window.launcher.unregister('foo')
```



Restore the pose.


## [pastedrop](com/pastedrop.js)

detects user copy/paste and file dragdrop action
and clipboard functions

```html 
  <a-entity pastedrop/>
```

| event        | target | info                                                                                               |
|--------------|--------|------------------------------------------|
| `pasteFile`  | self   | always translates input to a File object |


Restore the pose.


## [require](com/require('').js)

automatically requires dependencies or missing components

```javascript
await AFRAME.utils.require( this.dependencies )               (*) autoload missing components
await AFRAME.utils.require( this.el.getAttributeNames() )     (*) autoload missing components
await AFRAME.utils.require({foo: "https://foo.com/aframe/components/foo.js"},this)
await AFRAME.utils.require(["./app/foo.js","foo.css"],this)
```

> (*) = prefixes baseURL AFRAME.utils.require.baseURL ('./com/' e.g.)


## [window](com/window.js)

wraps a draggable window around a dom id or [dom](com/dom.js) component.

```html 
  <a-entity window="dom: #mydiv"/>
```

> depends on [AFRAME.utils.require](com/require.js)

| property         | type      | default                | info |
|------------------|-----------|------------------------|------|
| `title`          |`string`   | ""                     |      |
| `width`          |`string`   |                        |      |
| `height`         |`string`   | 260px                  |      |
| `uid`            |`string`   |                        |      |
| `attach`         |`selector` |                        |      |
| `dom`            |`selector` |                        |      |
| `max`            |`boolean`  | false                  |      |
| `min`            |`boolean`  | false                  |      |
| `x`              |`string`   | "center"               |      |
| `y`              |`string`   | "center"               |      |
| `class`          |`array`    | []                     |      |