api.js (v4.1.0), embed Tram-Lite version in TramLite and created comp…

…onents.

* separate the attaching of processors - included by default in tram-lite.js, excluded from api.js
* TramLite.version now includes the version of Tram-Lite that is live on the page
* TramLite.installed will tell you if Tram-Lite listeners have been attached to the document
* components made with TramLite now have a .tramLiteVersion

docs/pages/guiding-principles.html

@@ -39,6 +39,3 @@ <h3>4. Favor no-build environments</h3>
 	To this end, while we should be interoperable with other libraries, we should not be totally contingent on other
 	libraries to provide a delightful experience.
 </p>
-<p>
-	<em> Additionally, as much as possible, this project should try to adhere to this principle as much as possible. </em>
-</p>

docs/pages/install.html

@@ -29,7 +29,20 @@ <h2>script tag</h2>
 	</code-template-html>
 </p>
 
-<h2>types</h2>
+<h2>Javascript API</h2>
+<p>
+	If you only want access to the Javascript API, or are using tram-lite in a non-browser environment, you can pull just
+	the class definitions by pointing to the <code>api.js</code>. This is also useful if you don't want the side-effects
+	of Tram-Lite, or plan on using different versions of Tram-Lite in the same environment.
+
+	<code-template-html>
+		<template>
+			<script src="https://unpkg.com/tram-lite@4/output/api.js"></script>
+		</template>
+	</code-template-html>
+</p>
+
+<h2>Javascript Types</h2>
 
 <p>
 	If you use npm, you can get the type definitions by installing <code>tram-lite</code>, even if you don't use any build

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "tram-lite",
-	"version": "4.0.1",
+	"version": "4.1.0",
 	"description": "💡 HTML library for building and enhancing web-components",
 	"homepage": "https://tram-one.io/tram-lite/",
 	"repository": "https://github.com/Tram-One/tram-lite",
@@ -12,9 +12,13 @@
 	"scripts": {
 		"prestart": "npm run build",
 		"start": "serve .",
-		"build": "npm run bundle && npm run minify",
-		"bundle": "uglifyjs src/TramLite.js src/*.js -o output/tram-lite.js -b --comments all",
-		"minify": "uglifyjs output/tram-lite.js -o output/tram-lite.min.js -c -m",
+		"build": "npm run build:api && npm run build:tram-lite",
+		"build:api": "npm run bundle:api && npm run minify:api",
+		"bundle:api": "uglifyjs src/TramLite.js src/processors/*.js -o output/api.js -b --comments all --define APP_VERSION=\"'4.1.0'\"",
+		"minify:api": "uglifyjs output/api.js -o output/api.min.js -c -m",
+		"build:tram-lite": "npm run bundle:tram-lite && npm run minify:tram-lite",
+		"bundle:tram-lite": "uglifyjs output/api.js src/attach-processors.js -o output/tram-lite.js -b --comments all --define APP_VERSION=\"'4.1.0'\"",
+		"minify:tram-lite": "uglifyjs output/tram-lite.js -o output/tram-lite.min.js -c -m",
 		"prepublishOnly": "npm run build",
 		"pretest": "npm run build",
 		"test": "cypress open",

src/TramLite.js

@@ -1,4 +1,7 @@
 class TramLite {
+	static version = 'APP_VERSION';
+	static installed = false;
+
 	/**
 	 * a template tag function used to create new web-components.
 	 * {@link https://tram-one.io/tram-lite/#define Read the full docs here.}
@@ -28,6 +31,7 @@ class TramLite {
 
 		// Custom element class with tram-lite template support.
 		class CustomTramLiteElement extends HTMLElement {
+			static tramLiteVersion = 'APP_VERSION';
 			static get observedAttributes() {
 				// all of the template variables are attributes that we'll update on
 				return templateVariables;
@@ -175,8 +179,9 @@ class TramLite {
 	 * {@link https://tram-one.io/tram-lite/#appendShadowRootProcessor Read the full docs here.}
 	 * @param {string} matcher
 	 * @param {{ connect: function }} componentClass
+	 * @param {(node: Node) => boolean} [rootNodeTest=() => true]
 	 */
-	static appendShadowRootProcessor(matcher, componentClass) {
+	static appendShadowRootProcessor(matcher, componentClass, rootNodeTest = () => true) {
 		// save the original version of shadowRoot.append
 		const shAppend = ShadowRoot.prototype.append;
 
@@ -185,7 +190,9 @@ class TramLite {
 			// if any element in this shadowRoot matches our matcher,
 			//   run the `connect` function from this class
 			this.querySelectorAll(matcher).forEach((matchingElement) => {
-				componentClass.connect(matchingElement);
+				if (rootNodeTest(matchingElement.getRootNode().host)) {
+					componentClass.connect(matchingElement);
+				}
 			});
 		};
 	}

src/attach-processors.js

@@ -0,0 +1,4 @@
+ComponentDefinition.setupMutationObserverForTemplates();
+TramLite.appendShadowRootProcessor('[tl-controlled]', ControlledInput);
+TramLite.appendShadowRootProcessor('[tl-effect]', ComponentEffect);
+TramLite.installed = true;

src/ComponentDefinition.js → src/processors/ComponentDefinition.js

@@ -89,8 +89,9 @@ class ComponentDefinition {
 	/**
 	 * function to set up an observer to watch for when new templates are added,
 	 *   and process all the definitions in them
+	 * @param {Document} [targetRoot=document]
 	 */
-	static setupMutationObserverForTemplates() {
+	static setupMutationObserverForTemplates(targetRoot = document) {
 		/**
 		 * @param {MutationRecord[]} mutationRecords
 		 */
@@ -111,5 +112,3 @@ class ComponentDefinition {
 		observer.observe(document, { subtree: true, childList: true });
 	}
 }
-
-ComponentDefinition.setupMutationObserverForTemplates();

src/ComponentEffect.js → src/processors/ComponentEffect.js

@@ -59,5 +59,3 @@ class ComponentEffect {
 		});
 	}
 }
-
-TramLite.appendShadowRootProcessor('[tl-effect]', ComponentEffect);

src/ControlledInput.js → src/processors/ControlledInput.js

@@ -34,5 +34,3 @@ class ControlledInput {
 		});
 	}
 }
-
-TramLite.appendShadowRootProcessor('[tl-controlled]', ControlledInput);