Merge branch 'main' into hb-npm

.github/workflows/docs.yml

@@ -42,10 +42,6 @@ jobs:
       run: |
         npm run docs
 
-    - name: read the doc file
-      run: |
-        head -n 12 "./docs/js-api.md"
-
     - name: Get Docs content
       id: get-docs
       run: |
@@ -69,12 +65,15 @@ jobs:
 
     - name: Update Docs
       run: |
-        rm "./source/pages/02Javascript API.md"
-        mv -f "../doc/js-api.md" "./source/pages/02Javascript API.md"
+        rm -rf "./source/js-api*"
+        cp -a "../doc/js-api" "./source/"
+        cp -a "../doc/js-api-utils" "./source/"
+        cp -a "../doc/js-api-extras" "./source/"
+        ls -al ./source
 
     - name: Commit only if there are changes
       run: |
-        if [[ -n $(git diff --exit-code) ]]; then
+        if [[ -n $(git status --porcelain) ]]; then
           echo "Changes detected. Committing and pushing."
           git config user.name 'github-actions[bot]'
           git config user.email 'github-actions[bot]@users.noreply.github.com'

.github/workflows/readme-to-docs.yml

@@ -36,7 +36,7 @@ jobs:
         echo 'description: "An extendable WebComponents library for the Spatial Web"' >> $TEXT
         echo '---' >> $TEXT
         cat $TEXT $FILE > temp && mv temp $FILE
-        echo "<div class='centered'><a href='https://github.com/volumetrics-io/mrjs/edit/main/README.ms' target='_blank'>Suggest an edit on GitHub for README.md</a></div>" >> "$FILE"
+        echo "<div class='centered'><a href='https://github.com/volumetrics-io/mrjs/edit/main/README.md' target='_blank'>Suggest an edit on GitHub for README.md</a></div>" >> "$FILE"
         cat $FILE
 
     - name: Checkout documentation Repository
@@ -60,7 +60,7 @@ jobs:
           commit_message=$'👷 MR.js - Auto Generated README to Index Update 👷\n\nChanges at '"${GITHUB_SHA}"
           git add .
           git commit -m "$commit_message"
-          git push --quiet --set-upstream origin HEAD
+          git push --quiet --set-upstream origin HEAD --force
         else
           echo "No changes detected. Exiting without committing."
         fi

.gitignore

@@ -1,5 +1,10 @@
 # Build/Dist - ignore in this repo, they'll be built directly by render.com
-dist/*
+dist/assets*
+dist/examples/
+dist/samples/
+dist/index*
+dist/style*
+
 
 # Docs - ignore auto html docs in this repo, they'll be exported to the docs repo
 docs/*

CONTRIBUTING

@@ -0,0 +1 @@
+Please read our full contributing guide found on our main site: [here](https://docs.mrjs.io/contribute/)

README.md

@@ -1,61 +1,73 @@
-# mrjs
+![The mrjs logo](https://docs.mrjs.io/static/mrjs_nopadding.svg)
+
+An extensible library of Web Components for the spatial web.
 
 [![npm run build](https://github.com/Volumetrics-io/mrjs/actions/workflows/build.yml/badge.svg)](https://github.com/Volumetrics-io/mrjs/actions/workflows/build.yml) [![npm run test](https://github.com/Volumetrics-io/mrjs/actions/workflows/test.yml/badge.svg)](https://github.com/Volumetrics-io/mrjs/actions/workflows/test.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Volumetrics-io/mrjs/blob/main/LICENSE)
 
-An extensible WebComponents library for the Spatial Web
-
 ## Overview
 
-mrjs is a Mixed Reality first, webXR UI library meant to bootstrap spatial web app development. It implements much of the foundational work so that developers can spend less time on the basics and more time on their app.
+MRjs is a mixed-reality-first, WebXR user interface library meant to bootstrap spatial web development. It implements much of the foundational work so that developers can spend less time on the basics and more time on their app.
+
+## Main Links
+
+- [landing-page](https://mrjs.io) - includes about, info, and high def and community-created samples
+- [docs](https://docs.mrjs.io) - includes onboarding information, engine setup (ECS, Contributing, etc.), HTML tag helpers, and JavaScript API documentation
+- [dev-examples](https://examples.mrjs.io) - the examples from the main MRjs repository used as development explainers and for testing purposes.
 
 ## Getting started
 
-CDN:
+### Via a script tag in the `<head>` of your HTML file:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/mrjs@latest/dist/mr.js"></script>
+<head>
+    …
+    <script src="https://cdn.jsdelivr.net/npm/mrjs@latest/dist/mr.js"></script>
+    …
+</head>
 ```
 
-NPM:
+### Via NPM:
 
 ```sh
 npm i mrjs
 ```
 
-from source:
+### From source:
+
+> You will need Node [installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) on your computer
 
-clone this repo and run:
+First, [clone this repository](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories) and then run:
 
 ```sh
 npm install && npm run build
 ```
 
-in headset testing:
+To test in headset:
 
 ```sh
 npm run server
 ```
 
-Documentation:
+### Documentation:
 
-Check [docs.mrjs.io](https://docs.mrjs.io) for the full documentation or our [repo](https://github.com/Volumetrics-io/documentation).
+Check [docs.mrjs.io](https://docs.mrjs.io) or our [repository](https://github.com/Volumetrics-io/documentation) for the full documentation.
 
-For local documentation or to check the local output when writing your own PR to see how it will update, run the below command. As a heads up, order of creation of docs depends on your operating system, so if when you run this and the order looks different, no worries - in the repo itself our action will handle that for you and default to use the right version for these automatically generated docs.
+For local documentation or to check the local output when writing your own PR to see how it will update, run the below command. As a heads-up, the order of creation of docs depends on your operating system, so if when you run this and the order looks different, no worries - in the repository itself our action will handle that for you and default to use the right version for these automatically generated docs.
 
 ```sh
 npm run docs
 ```
 
 ## HTTPS Requirement
 
-In order to test on headset, WebXR requires that your project be served using an HTTPS server. If you're using WebPack you can achieve this by utilizing the [DevServer webpack plugin](https://webpack.js.org/configuration/dev-server/) with `https: true`. 
+To test in headset, WebXR requires that your project be served using an HTTPS server. If you're using Webpack, you can achieve this by utilizing the [Dev Server webpack plugin](https://webpack.js.org/configuration/dev-server/) with `https: true`. 
 
 Here are some additional solutions:
 
 - [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) for VS Code
-- [via python](https://anvileight.com/blog/posts/simple-python-http-server/)
+- [via Python](https://anvileight.com/blog/posts/simple-python-http-server/)
 
-Both options require you generate an ssl certificate & key via openssl:
+Both options require you generate an SSL certificate and a key via OpenSSL:
 
 ```sh
 openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365
@@ -80,7 +92,6 @@ Create 2D UI using CSS and `mr-panel`
     font-size: 5vw;
     line-height: 100%;
     color: rgba(24, 24, 24, 0.75);
-
     grid-column: 2;
 }
 
@@ -113,7 +124,7 @@ mr-img {
 
 ## Built-in Physics Engine
 
-Rapier.js is fully integrated out of the box. We use it to power collision based hand-interactions, but also to support other common features such as:
+Rapier.js is fully integrated out of the box. It is used to power collision-based hand interactions, but also to support other common features such as:
 
 - Gravity
 - Rag doll physics
@@ -124,19 +135,19 @@ Rapier.js is fully integrated out of the box. We use it to power collision based
 
 ## Extensible
 
-Designed to be extensible, mrjs provides a familiar interface via THREE.js and the Custom Elements API, and leveled up with a built in ECS.
+Designed to be extensible, MRjs provides a familiar interface via THREE.js, the Custom Elements API, and is leveled up with a built-in ECS (Entity Component System).
 
-### ECS
+### Entity Component System
 
-mrjs is designed from the ground up using the Entity-Component-System Architecture. This is a common architecture implemented by Game Engines such as Unity, Unreal, and Apple's RealityKit.
+MRjs is designed from the ground up using the Entity-Component-System Architecture. This is a common architecture implemented by Game Engines such as Unity, Unreal, and RealityKit.
 
 #### Entity
 
 An Entity is an object. It stores only the most fundamental data, such as a unique identifier, a THREE.js Object3D, a physics body, and dimension data such as width and scale.
 
 Any `mr-*` tag within the `mr-app` is an Entity. `mr-entity` is the spatial equivalent of a `div`.
 
-Creating a custom Entity is as simple as creating a Custom Element via the WebComponents API.
+Creating a custom Entity is as simple as creating a Custom Element via the Web Components API.
 
 Example:
 
@@ -157,9 +168,9 @@ customElements.get('mr-spacecraft') || customElements.define('mr-spacecraft', Sp
 
 #### Systems
 
-A System contains logic that is applied to all entities that have a corresponding Component, using the data stored by the component. Unlike Entities & Components, Systems have no HTML representation and are implemented entirely in JS.
+A System contains logic that is applied to all entities that have a corresponding Component, using the data stored by the component. Unlike Entities & Components, Systems have no HTML representation and are implemented entirely in JavaScript.
 
-When a component is attached or detatched from an entity, it is added or removed from its System's registry of entities.
+When a component is attached to or detached from an entity, it is added or removed from its System's registry of entities.
 
 Example:
 
@@ -172,7 +183,7 @@ class OrbitSystem extends System{
     // called every frame
     update(deltaTime, frame) {
         for(const entity in this.registry) {
-            // Update entitiy position
+            // Update entity position
             let component = entity.components.get('orbit')
             component.radius
             component.target
@@ -192,18 +203,18 @@ class OrbitSystem extends System{
         //...
     }
 
-    // do something when an orbit component is detatched
+    // do something when an orbit component is detached
     detachedComponent(entity) {
         //...
     }
 }
 ```
 
-When you define a custom system, it listens for events triggered when the System's corresponding component is attached, updated, or detatched. in the above case, `data-comp-orbit`.
+When you define a custom system, it listens for events triggered when the System's corresponding component is attached, updated, or detached. In the above case, `data-comp-orbit`.
 
 #### Components
 
-Components are attached to entities and used to store data. in mrjs they are implemented using data attributes beginning with the prefix `data-comp-`.
+Components are attached to entities and used to store data. In MRjs they are implemented using data attributes beginning with the prefix `data-comp-`.
 
 Example:
 

__tests__/examplesTesting.test.js

@@ -5,7 +5,7 @@ import fs from 'fs/promises'; // Node.js file system module with promises
 // using a server to host them works best, so just grabbing from github is fine for now.
 const MODELS_URL = 'https://github.com/Volumetrics-io/mrjs/main/samples/assets/models/'
 
-const fileNames = ['../index', 'anchors', 'embed']; // Replace with your actual file names
+const fileNames = ['../index', 'anchors', 'audio', 'embed', 'models', 'skybox'];
 
 describe('Test the Examples', () => {
     let browser;
@@ -38,8 +38,8 @@ describe('Test the Examples', () => {
                 `<script src="/mr.js"></script>`,
                 `<script src="../dist/mr.js"></script>`);
             htmlContent = htmlContent.replace(
-                `<link rel="stylesheet" type="text/css" href="${fileName}.css" />`,
-                `<link rel="stylesheet" type="text/css" href="./dist/examples/${fileName}.css" />`);
+                `<link rel="stylesheet" type="text/css" href="${fileName}-style.css" />`,
+                `<link rel="stylesheet" type="text/css" href="./dist/examples/${fileName}-style.css" />`);
 
             await page.setContent(htmlContent);
 

create-docs.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+# Define base output directories
+output_dir='docs'
+js_api_dir="${output_dir}/js-api"
+js_api_utils_dir="${output_dir}/js-api-utils"
+js_api_extras_dir="${output_dir}/js-api-extras"
+
+# Remove the existing output directories if they exist and create new ones
+rm -rf "$js_api_dir" "$js_api_utils_dir" "$js_api_extras_dir"
+mkdir -p "$js_api_dir" "$js_api_utils_dir" "$js_api_extras_dir"
+
+# Function to process .js files
+process_js_files() {
+  local source_dir=$1
+  local output_dir=$2
+  local ignore_index_js_subdirs=$3
+  local counter=0 # Local counter for each call
+
+  # Construct the base find command to exclude 'index.js' files directly
+  local find_cmd="find \"$source_dir\" -type f -name '*.js' ! -name 'index.js' ! -name '_*'"
+
+  # If ignoring subdirectories with index.js
+  if [[ "$ignore_index_js_subdirs" == "true" ]]; then
+    local ignore_dirs=$(find "$source_dir" -mindepth 2 -type f -name 'index.js' -exec dirname {} \; | sort | uniq)
+    for dir in $ignore_dirs; do
+      local escaped_dir=$(printf '%q' "$dir")
+      find_cmd+=" ! -path \"$escaped_dir/*\""
+    done
+  fi
+
+  eval "$find_cmd" | while read file; do
+    # Format the counter with leading zeros
+    printf -v formatted_counter "%03d" $counter
+
+    # Generate new Markdown file name by prepending the counter to the base name of the .js file
+    md_file="${output_dir}/${formatted_counter}$(basename "${file%.js}.md")"
+
+    # Extract the title from the Markdown file name, accurately reflecting the original file name
+    local original_file_name=$(basename "$file" .js)
+    local title="${original_file_name}"
+
+    # Generate Markdown content
+    {
+      echo '---'
+      echo "title: ${title}"
+      echo '---'
+      echo "# ${title}"
+      echo ''
+      jsdoc2md "$file"
+    } > "$md_file"
+    echo "<div class='centered'><a href='https://github.com/volumetrics-io/mrjs/edit/main/$file' target='_blank'>Suggest an edit on GitHub for ${original_file_name}.js</a></div>" >> "$md_file"
+
+    # Increment the local counter
+    ((counter++))
+  done
+}
+
+# Process files for each directory
+process_js_files "src" "$js_api_dir" true # true to ignore subdirs with index.js for js-api
+process_js_files "src/utils" "$js_api_utils_dir" false
+process_js_files "src/extras" "$js_api_extras_dir" false