Skip to content

M-CreativeLab/jsar-dom

Repository files navigation

JSAR-DOM

npm version Build Status Integration Test Status

This project JSAR-DOM is a TypeScript implementation of many Web standards, notably the WHATWG DOM, CSSOM, WebXR and XSML, for use in Node.js and browser.

This project is a part of the JSAR, which is a Web-compatible runtime for integrating XR applications (especially Interactive Digital Product) into native environments like Unity.

JSAR-DOM is a fork of jsdom/jsdom project and its children projects with a TypeScript rewrite and added the support for XSML and SCSS.

Interactive Digital Product (IDP) represents a virtual entity designed to digitally replicate and interactively showcase real-world products in metaverse. This representation emphasizes the digital nature of the item, allowing users to engage with it in an interactive manner. IDPs serve as dynamic and immersive digital counterparts to physical products, offering a novel and engaging user experience within a virtual environment.

Features

  • Web-standards APIs notably including WHATWG DOM, CSSOM, WebXR and XSML.
  • ECMAScript Modules with TypeScript, WebAssembly and non-script assets supports.
  • No Build At All to get started for application developers.

Getting Started

JSAR-DOM is designed to be a drop-in and easy-to-use replacement for the jsdom package. After installing it, you just need to change your require or import call from jsdom to @yodaos-jsar/dom:

import { JSARDOM } from '@yodaos-jsar/dom';
// or
const { JSARDOM } = require('@yodaos-jsar/dom');

Then you can use it exactly as you would use jsdom:

const dom = new JSARDOM(`
<xsml>
  <head>
    <style>
      cube {
        rotation: 0 45 30;
      }
      plane {
        position: 0.25 0.5 -1;
      }
    </style>
  </head>
  <space>
    <cube />
    <plane height="0.5" width="1.5">
      <div>
        <span>Hello JSAR!</span>
        <span style="font-size: 50px;">Type your XSML in the below input</span>
      </div>
      <style type="text/css">
        div {
          display: flex;
          flex-direction: column;
          height: 100%;
          width: 100%;
          gap: 20px;
        }
        span {
          flex: 1;
          color: red;
          font-size: 150px;
          line-height: 1.5;
        }
      </style>
    </plane>
  </space>
</xsml>
`, {
  url: 'https://m-creativelab.github.io/jsar-dom/',
  nativeDocument: yourNativeDocument,
});

await dom.load();

The above code is available at https://m-creativelab.github.io/jsar-dom/.

Because JSAR-DOM is not going to be a emulator of the traditional browser, it's an in-production implementation of the WHATWG DOM, CSSOM, WebXR and XSML for XR applications, so an instance of implementing the NativeDocument interface must be pass to the constructor, which implemented the underlying stuffs like rendering and event handling.

Using headless NativeDocument implementation

If you want to use JSAR-DOM in a headless environment, you can use the HeadlessNativeDocument implementation, which is a headless implementation of the NativeDocument interface.

$ ts-node src/impl-headless.ts ./fixtures/simple.xsml

At JSAR-DOM project, we use the this implementation for tests purpose, you could also use it to see how to write a NativeDocument implementation, or just run a XSML application in a headless environment.

Using Babylon.js NativeDocument implementation

Inside the JSAR-DOM project, we also provide a Babylon.js implementation of the NativeDocument interface, which is an implementation of the NativeDocument interface based on the Babylon.js engine on classic Web browsers.

To use it, open the GitHub hosted m-creativelab.github.io/jsar-dom or build locally by following instructions:

$ cd pages
$ npm install
$ npx webpack
$ open ./index.html

Then you could type a HTTP or HTTPS URL of a XSML to view in the browser.

Babylon.js Implementation is a good example of how to integrate JSAR-DOM applications into a classic Web ecosystem, see ./pages/impl-babylonjs.ts for the full source code.

Installation

npm install @yodaos-jsar/dom

What's XSML?

XSML: eXtensible Spatial Markup Language.

It is a XML-based markup language for describing XR applications. It's designed to be a subset of HTML, and it's also a part of the JSAR project.

Why not X3D

X3D is a great standard for describing 3D scenes after VRML, but it's not designed for Web developers and not extending the HTML standard, XSML is designed to be a subset of HTML and it's easy to learn for Web developers.

An example of XSML:

<xsml>
  <head>
    <title>Hello JSAR-DOM</title>
  </head>
  <space>
    <sphere />
  </space>
</xsml>

What's SCSS?

SCSS: Spatial Cascading Style Sheets.

It's a CSS-like language for styling XSML elements, it's designed to be a part of new CSS standard and compatible with the CSS3 standard. SCSS added some new features for styling spatial elements, like rotation, position, scaling, materials and textures.

An example of SCSS:

@material litered {
  diffuse-color: red;
}

sphere {
  scaling: 1.2 1.2 1;
  material: "litered"
}

License

See Apache-2.0.