import and export components (v4.2.0) #40

JRJurman · 2023-10-07T02:15:32Z

Summary

This version is available by pointing to tram-lite@beta.
https://unpkg.com/tram-lite@beta

This PR adds the ability for developers to import and export component definitions.

This allows developers to organize components, create libraries of components, and allow other developers to consume the components without needing Tram-Lite.

Importing Component Definitions

<script src="https://unpkg.com/tram-lite@4/output/import-components.js" tl-components="./x-button.html"></script>

This method allows another developer to point to an HTML component definition, and load it directly in their page. It requires no other build steps.

Exporting Component Definitions

npx tram-lite@4 export-components x-button.html

This method is a build step that transforms an html component definition into javascript that can be imported like any other JS library.

There is full documentation that can be read by cloning this branch and loading npm run docs.

Other Changes

As part of the above changes, I've updated the build tooling to be a separate build.js script, and moved some of the tests around. This will likely continue to evolve over time, but was needed here to reign-in on some of the complexity that we have for all the different ways people can use components 👏

Checklist

PR Summary
PR Annotations
Tests
Version Bump

JRJurman

Inline Comments for Peer Review

JRJurman · 2023-10-08T14:32:01Z

docs/index.html

+		<!-- styles -->
+		<style>
+			:root {
+				background: rgb(31, 44, 57);
+				background: linear-gradient(140deg, rgba(31, 44, 57, 1) 0%, rgba(49, 49, 26, 1) 100%);
+			}
+		</style>


adding a nice gradient to the background of the main website - including this here so that we always have this (even if the external stylesheet doesn't load).

The gradient itself was created with cssgradient.io

JRJurman

Moving comments inline so that they are available for review 😅

JRJurman · 2023-10-08T17:06:15Z

build.js

+// This script contains all the steps for generating the output results.
+// This can be triggered by running `npm run build`
+//
+// A majority of this file uses the UglifyJS API
+// https://www.npmjs.com/package/uglify-js


this new build.js replaces the set of scripts that were in the package.json. This is a more organized way to bundle and expose all the different scripts that we need, allows us to write comments, and have more consistent behavior across all the generated scripts.

Candidly, this is slightly more error prone, compared to the CLI interface (which is better documented), but all in all, worth the migration.

JRJurman · 2023-10-08T17:06:41Z

cypress/spec.cy.js

@@ -1,65 +0,0 @@
-describe('Tram-Lite Example Components', () => {


This file was moved to inline.cy.js

JRJurman · 2023-10-08T17:07:06Z

docs/pages/importing-and-exporting.html

@@ -0,0 +1,120 @@
+<h2>Importing And Exporting Components</h2>


New documentation for the functionality added in this PR! 📝
I would advocate reviewing this locally, over reading the source code 😅

JRJurman · 2023-10-08T17:07:29Z

examples/components/build-test-components.sh

+node output/export-components.js examples/components/ex-progressbar.html examples/components/ex-temperature.html examples/components/ex-container.html examples/components/ex-colorpicker.html -o examples/components/example-components.js
+node output/export-components.js examples/components/ex-colorpicker.html -o examples/components/ex-colorpicker.js


Right now, this is just a shell script, but we should migrate this with a JS API (separate issue #41)

JRJurman · 2023-10-08T17:07:46Z

examples/components/ex-colorpicker.html

@@ -0,0 +1,15 @@
+<ex-colorpicker width="100px">


This is a copy-paste of the inline colorpicker example. Some thinking should happen around making this more consistent (see #42)

JRJurman · 2023-10-08T17:08:06Z

examples/export/export.cy.js

@@ -0,0 +1,29 @@
+describe('Tram-Lite Example Components (via export)', () => {


Along with making the new example/test pages, we've also moved the cypress tests to be adjacent to the page files. This mimics the pattern common with unit-tests (where the tests are adjacent to the source code).

JRJurman · 2023-10-08T17:08:34Z

examples/index.html

-<!doctype html>
-<html lang="en">
-	<head>
-		<title>Tram-Lite Example Components</title>


This was renamed to inline/index.html

JRJurman · 2023-10-08T17:10:13Z

src/TramLite.js

@@ -194,18 +194,18 @@ 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]
+	 * @param {ShadowRoot} [shadowRoot=ShadowRoot.prototype]


The major change here is the update to appendShadowRootProcessor, which for a short while supported a rootNodeTest - this was never documented though, so not considering this a breaking change.

Instead, we are supporting a shadowRoot parameter, which lets people focus the processor on a single component (useful when we don't want to update the behavior of all components everywhere).

JRJurman · 2023-10-08T17:10:32Z

src/processors/ComponentDefinition.js

+	/**
+	 * utility function to extract js template strings, so that they can be passed into a template tag function
+	 */
+	static extractTemplateVariables(templateString) {


extracting out the template variable parsing so we can use that in the ImportComponent logic. This is otherwise unchanged.

chtinahow

Lgtm

JRJurman added 2 commits October 4, 2023 20:16

build component and test

7e93872

working import-component output

35b8c1e

JRJurman force-pushed the import-export-component branch from 792b86f to 35b8c1e Compare October 7, 2023 02:17

JRJurman added 5 commits October 6, 2023 22:19

remove jsdom

74b2899

4.2.0

668ccfb

hybrid test, enclose component import, non-module and non-install build

79223a3

simplify build tooling

8ae56c4

enclose

6a2a19d

JRJurman changed the title ~~import-component script~~ import-component script (v4.2.0) Oct 7, 2023

JRJurman added 16 commits October 7, 2023 16:10

export-script logic

0d8e747

move test files to relevant locations

77e550b

fix build scripts, fix safari issue, start documentation

13e7843

final documentation

d78c514

include the export command as a binary

9b4ddab

4.2.0-beta.0

1636823

fix export script

023a5eb

4.2.0-beta.1

76bd25d

fix export

a24696b

4.2.0-beta.2

e161e56

use relative paths for export

a72da44

4.2.0-beta.3

f6918ee

use real relative paths

79e1499

4.2.0-beta.4

fd506dd

more comments for build.js

b38bb47

fix hyperlink

3b5ccd9

This was referenced Oct 8, 2023

Javascript API for Exporting Components #41

Open

Clean up Test Code Organization #42

Open

JRJurman added 3 commits October 8, 2023 10:49

remove generated components

9fd79ff

documentation for new shadowRoot parameter

03daa12

add comments pointing to documentation

ec47fd9

JRJurman commented Oct 8, 2023

View reviewed changes

JRJurman marked this pull request as ready for review October 8, 2023 16:58

4.2.0

b7de92b

JRJurman commented Oct 8, 2023

View reviewed changes

JRJurman changed the title ~~import-component script (v4.2.0)~~ import and export components (v4.2.0) Oct 8, 2023

JRJurman added 3 commits October 8, 2023 17:26

support and tests for multi-component definitions

015bcfa

update documentation

a2141fa

remove todolist component

961b8b0

chtinahow approved these changes Oct 8, 2023

View reviewed changes

JRJurman merged commit ae0348d into main Oct 8, 2023

JRJurman deleted the import-export-component branch October 8, 2023 22:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

import and export components (v4.2.0) #40

import and export components (v4.2.0) #40

JRJurman commented Oct 7, 2023 •

edited

Loading

JRJurman left a comment

JRJurman Oct 8, 2023

JRJurman left a comment

JRJurman Oct 8, 2023

JRJurman Oct 8, 2023

JRJurman Oct 8, 2023

JRJurman Oct 8, 2023

JRJurman Oct 8, 2023

JRJurman Oct 8, 2023

JRJurman Oct 8, 2023

JRJurman Oct 8, 2023

JRJurman Oct 8, 2023

chtinahow left a comment

		@@ -1,65 +0,0 @@
		describe('Tram-Lite Example Components', () => {

		@@ -0,0 +1,120 @@
		<h2>Importing And Exporting Components</h2>

		node output/export-components.js examples/components/ex-progressbar.html examples/components/ex-temperature.html examples/components/ex-container.html examples/components/ex-colorpicker.html -o examples/components/example-components.js
		node output/export-components.js examples/components/ex-colorpicker.html -o examples/components/ex-colorpicker.js

		@@ -0,0 +1,29 @@
		describe('Tram-Lite Example Components (via export)', () => {

import and export components (v4.2.0) #40

import and export components (v4.2.0) #40

Conversation

JRJurman commented Oct 7, 2023 • edited Loading

Summary

Importing Component Definitions

Exporting Component Definitions

Other Changes

Checklist

JRJurman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JRJurman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chtinahow left a comment

Choose a reason for hiding this comment

JRJurman commented Oct 7, 2023 •

edited

Loading