Wave.js

Web-based Atomic Viewer and Editor in JavaScript. Wave.js is a library for atomic visualization and editing written in JavaScript enabling visualization of material structures from atoms up on the web.

The library was originally designed as part of and presently powers materials design capabilities of the Mat3ra.com platform.

1. Functionality.

As below:

• the package provides a web environment for the visualization of atomic structures and is written in ECMAScript 2015 (ES6) for use on the web
• ESSE Data Convention is employed to organize and store information [1] via Made.js
• THREE.js is used for 3d visualization purposes
• High-level classes for the representation of the viewer and modular mixins for the associated functionality, ie:
  • Atoms,
  • Bonds,
  • Cell,
  • Controls,
  • Interactive structure editor,
  • Labels and Measurements,
  • and others.
• wrapper components for React:
  • ThreeDEditor — the package's public component, with control trigger button panels, the edit toolbar and the host-app API
  • WaveComponent — owns the Wave instance lifecycle; used internally by ThreeDEditor and not currently exported from exports.js

The package is written in a modular way easy to extend. Contributions can be in the form of additional functionality modules developed, or feature requests and bug/issue reports.

2. Installation.

From NPM for use within a software project:

npm install @mat3ra/wave.js

From source to contribute to development:

git clone git@github.com:mat3ra/wave.js.git

3. Contribution.

This repository is an open-source work-in-progress and we welcome contributions.

3.1. Adding new functionality.

We suggest forking this repository and introducing the adjustments there to be considered for merging into this repository as explained in more details here, for example.

3.2. Source code conventions.

Wave.js is written in EcmaScript 6th edition [2] with the application of object-oriented design patterns encapsulating key concepts following the conventions below.

1. One main class exposing the functionality with a set of mixins (implemented through mixwith) containing domain-specific functionality inside mixins folder

2. The implementation of the viewer uses a native HTML node to initialize a Three.js rendering context, components folder further contains the wrapper React components for convenient use in web applications.

3.3. TODO list.

Desirable features for implementation:

• React Three Fiber
• migration to React 18+ (currently blocked on the enzyme test adapter)
• remaining roadmap items in the editor design spec

Note that the in-viewer structure editor replaced the previous standalone THREE.js editor modal; its generic 3D-authoring features (primitives, lights, materials editor, JS scripting console) and its outliner panel are deliberately out of scope — see the spec.

4. Development.

There are two types of tests: asserting Wave class functionality and testing React components. Wave class tests use snapshot testing in which an snapshot of the WebGL [3] context is taken and compared with the reference. The test will fail if the two snapshots do not match. This is admittedly a bit fragile, and future work may improve the test coverage such that this is no longer necessary. React component tests use Enzyme [4] that makes DOM manipulation and traversal easier.

Note that snapshots may be slightly different depending on operating systems leading to comparison with a tolerance. A docker-compose.yml is provided for convenience. To run the tests, execute the following commands:

docker-compose build
docker-compose run test

Or directly on a host. Note the two prerequisites: fixtures and visual baselines are partly in Git LFS, and headless-gl needs a real GL context (mesa + xvfb on Linux — see the Dockerfile for the package list).

git lfs install && git lfs pull
npm ci
xvfb-run -s "-ac -screen 0 1024x768x24" npm test

4.1. Important Notes.

1. Keep the tests directory structure similar to the main codebase directory structure. Every JS module in the main codebase should have a corresponding module in tests directory which implements the tests for provided functionality.

2. Add tests fixtures into fixtures directory as plain files. Only binary visual baselines (tests/__tests__/__snapshots__/expected/*.png and *.snap) are stored on Git LFS [6] — small JSON fixtures deliberately are not, so that a clone without git-lfs can still run the suite.

3. Add Jest configuration into setupFiles module.

4. Use setupFilesAfterEnv module to implement tests hooks.

5. Make sure to use async keyword for Wave class tests as they are asynchronous.

4.2. Dependencies.

This package depends on Made.js and on stock THREE.js. See package.json for the full list.

4.3. Using cove for local development

In case you need to link Cove into the app for local development you need

1. Add local path of Cove to package.json

    "@mat3ra/cove": "file:../../cove.js"

2. Run the app

    npm start

If you need to re-link it again, remove node_modules in cove and the app, run npm install, then run npm start again.

4.4. Deployed previews (Netlify)

netlify.toml configures a deploy of the demo viewer, so a branch can be tried in a real browser. Every pull request gets its own Deploy Preview URL.

That matters because the Jest suite structurally cannot reach some things — real browser event ordering, pointer capture, CSS layout at a given viewport, and GPU rendering are all listed as out-of-reach in the editor spec §8.1, which is why MANUAL_SMOKE.md exists. A preview URL is where that checklist gets run.

Note that vite.config.js sets base: "/wave.js/" for the GitHub Pages deploy; Netlify serves from the domain root, so its build overrides the base on the command line (npx vite build --base=/). Building for Pages is unaffected.

One-time setup, which cannot be done from this repository: link the repo to a Netlify site (Netlify UI → Add new site → Import an existing project → pick this repo). The build command, publish directory and Node version all come from netlify.toml, so nothing needs configuring in the UI.

5. Links.

1. Exabyte Source of Schemas and Examples (ESSE), Github Repository

2. ECMAScript 2015 Language Specifications

3. Headless GL, Github Repo

4. Enzyme, A JavaScript Testing Utility For React, Github Repo

5. Jest Testing Framework, Official Website

6. Git LFS, Official Website