Merge pull request #37 from EPA-WG/develop

0.0.17

README.md

@@ -1,7 +1,7 @@
 # custom-element
 `Declarative Custom Element` (DCE) is a part of pure `Declarative Web Application` stack. A proof of concept as a part of 
 [WCCG in Declarative custom elements](https://github.com/w3c/webcomponents-cg/issues/32#issuecomment-1321037301) and [Declarative Web Application](https://github.com/EPA-WG/dwa#readme)
-discussion. The functionality of DCE and its data access does not require programming using JavaScript. 
+discussion. **NO-JS** The functionality of DCE and its data access does not require programming using JavaScript. 
 
 It allows to define custom HTML tag with template filled from slots, attributes and data `slice` as of now from  
 [local-storage][local-storage-demo],  [http-request][http-request-demo], [location][location-demo].
@@ -133,10 +133,19 @@ constructor creates XML with
 
 DOM content is replaced with results of instance XML transformation by declaration XSLT.
 
+# `tag` attribute
+allows to define the Custom Element tag registered by `window.customElements.define()`.
+
+If omitted, the tag is auto-generated and the content is rendered inline.
+```html
+<custom-element> my tag is {tag} </custom-element>
+```
+See [demo](https://unpkg.com/@epa-wg/[email protected]/demo/external-template.html) for `tag` attribute use.
+
 # `src` attribute
 allows to refer either external template or template within external library by `#id` hash in URL.
 
-See [demo](demo/external-template.html) with various samples.
+See [demo](https://unpkg.com/@epa-wg/[email protected]/demo/external-template.html) with various samples.
 
 ## types of template
 * HTML with DCE syntax ( slots, data slices, xslt operators, etc. )
@@ -308,9 +317,9 @@ within template
 [github-image]:   https://cdnjs.cloudflare.com/ajax/libs/octicons/8.5.0/svg/mark-github.svg
 [npm-image]:      https://img.shields.io/npm/v/@epa-wg/custom-element.svg
 [npm-url]:        https://npmjs.org/package/@epa-wg/custom-element
-[coverage-image]: https://unpkg.com/@epa-wg/[email protected].16/coverage/coverage.svg
-[coverage-url]:   https://unpkg.com/@epa-wg/[email protected].16/coverage/lcov-report/index.html
-[storybook-url]:  https://unpkg.com/@epa-wg/[email protected].16/storybook-static/index.html?path=/story/welcome--introduction
+[coverage-image]: https://unpkg.com/@epa-wg/[email protected].17/coverage/coverage.svg
+[coverage-url]:   https://unpkg.com/@epa-wg/[email protected].17/coverage/lcov-report/index.html
+[storybook-url]:  https://unpkg.com/@epa-wg/[email protected].17/storybook-static/index.html?path=/story/welcome--introduction
 [sandbox-url]:    https://stackblitz.com/github/EPA-WG/custom-element?file=index.html
 [webcomponents-url]: https://www.webcomponents.org/element/@epa-wg/custom-element
 [webcomponents-img]: https://img.shields.io/badge/webcomponents.org-published-blue.svg

custom-element.d.ts

@@ -1,4 +1,35 @@
 export function log(x: any): void;
+
+/**
+ * @summary Declarative Custom Element as W3C proposal PoC with native(XSLT) based templating
+ * ```html
+ * <custom-element tag="my-element">
+ *             <template>
+ *                 <xsl:param name="p1" >default_P1</xsl:param>
+ *                 <style>
+ *                     color:green;
+ *                     b{ color: blue;}
+ *                     input:checked+b{ color: darkblue; text-shadow: 0 0 4px springgreen;}
+ *                 </style>
+ *                 <label>
+ *                     green
+ *                     <input type="checkbox" value="Glowing Blue" checked/><b>blue</b>
+ *                 </label>
+ *                 p1:{$p1}
+ *             </template>
+ *         </custom-element>
+ * <my-element p1="abc"></my-element>
+ * ```
+ *
+ * @extends HTMLElement
+ * @tag custom-element
+ * @tag-name custom-element
+ * @attr {boolean} hidden - hides DCE definition to prevent visual appearance of content. Wrap the payload into template tag to prevent applying the inline CSS in global scope.
+ * @attr {string} tag - HTML tag for Custom Element. Used for window.customElements.define(). If not set, would be generated and DCE instance rendered inline.
+ * @attr {string} src - full, relative, or hash URL to DCE template.
+ *
+ */
 export class CustomElement extends HTMLElement {
+    static observedAttributes : string[];
 }
 export default CustomElement;

custom-element.js

@@ -386,6 +386,7 @@ export function assureUID(n,attr)
     export class
 CustomElement extends HTMLElement
 {
+    static observedAttributes = ['src','tag','hidden'];
     async connectedCallback()
     {
         const templateRoots = await loadTemplateRoots( attr( this, 'src' ), this )
@@ -521,10 +522,11 @@ CustomElement extends HTMLElement
             window.customElements.define( tag, DceElement);
         else
         {   const t = tagName;
+            this.setAttribute('tag', t );
             window.customElements.define( t, DceElement);
             const el = document.createElement(t);
             this.getAttributeNames().forEach(a=>el.setAttribute(a,this.getAttribute(a)));
-            el.append(...[...this.childNodes].filter(e=>e.localName!=='style'))
+            el.append(...[...this.childNodes].filter( e => e.localName!=='style') );
             this.append(el);
         }
     }

demo/parameters.html

@@ -32,7 +32,7 @@
             <xsl:param name="p3" select="//p3 ?? 'def_P3' "  ></xsl:param>
             p1:{$p1} <br/> p2: {$p2} <br/> p3: {$p3}
         </custom-element>
-        <dce-link id="dce1"></dce-link>
+        <dce-link id="dce1" ></dce-link>
         <section>
             <dce-link id="dce2" p1="123" p2="override ignored as select is defined"></dce-link> <br/>
             <div><input id="i1" value="p1" />  <button onclick="dce2.setAttribute('p1',i1.value)"> set p1</button> </div>

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@epa-wg/custom-element",
-    "version": "0.0.16",
+    "version": "0.0.17",
     "description": "Declarative Custom Element as W3C proposal PoC with native(XSLT) based templating",
     "browser": "custom-element.js",
     "module": "custom-element.js",
@@ -12,15 +12,15 @@
     "files": [
         "*"
     ],
-    "type": "module",
-    "types": "./custom-element.d.ts",
     "scripts": {
         "dev:help": "echo \"needed for sandbox demo\"",
         "dev": "bash bin/stackblitz.sh",
         "start": "npm i --no-save @web/dev-server && web-dev-server --node-resolve",
         "test": "echo \"test would reside in https://github.com/EPA-WG/custom-element-test\" && exit 0",
         "typings": "npx -p typescript tsc custom-element.js --declaration --allowJs --emitDeclarationOnly "
     },
+    "type": "module",
+    "types": "./custom-element.d.ts",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/EPA-WG/custom-element.git"
@@ -45,5 +45,6 @@
     "funding": {
         "type": "patreon",
         "url": "https://www.patreon.com/sashafirsov"
-    }
+    },
+    "web-types": "./web-types.json"
 }

web-types.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json.schemastore.org/web-types",
+  "name": "@epa-wg/custom-element",
+  "version": "0.0.17",
+  "js-types-syntax": "typescript",
+  "description-markup": "markdown",
+  "contributions": {
+    "html": {
+      "elements": [
+        {
+          "name": "custom-element",
+          "description": "Declarative Custom Element as W3C proposal PoC with native(XSLT) based templating",
+          "doc-url": "https://github.com/EPA-WG/custom-element?tab=readme-ov-file#custom-element",
+          "attributes": [
+            {
+              "name": "hidden",
+              "description": "hides DCE definition to prevent visual appearance of content. Wrap the payload into template tag to prevent applying the inline CSS in global scope.",
+              "required": false,
+              "doc-url": "https://developer.mozilla.org/en-US/docs/web/html/global_attributes/hidden",
+              "value": {
+                "type": "boolean"
+              }
+            },
+            {
+              "name": "tag",
+              "description": "HTML tag for Custom Element. Used for window.customElements.define(). If not set, would be generated and DCE instance rendered inline. ",
+              "default": "",
+              "required": false,
+              "doc-url": "https://github.com/EPA-WG/custom-element?tab=readme-ov-file#tag-attribute",
+              "value": {
+                "type": "string"
+              }
+            },
+            {
+              "name": "src",
+              "description": "full, relative, or hash URL to DCE template.",
+              "default": "",
+              "required": false,
+              "doc-url": "https://github.com/EPA-WG/custom-element?tab=readme-ov-file#src-attribute",
+              "value": {
+                "type": "URL"
+              }
+            }
+          ],
+          "slots": [],
+          "js": {
+            "events": [
+              {
+                "name": "value:changed",
+                "description": "Emitted when data changes. Can be used for state serialization in hydration flow"
+              }
+            ],
+            "properties": [
+              {
+                "name": "value",
+                "type": "string",
+                "default": "",
+                "description": "DCE state. Can be used for state serialization in hydration flow. Format TBD, most likely encoded XML string"
+              }
+            ]
+          },
+          "css": {
+            "properties": [
+            ]
+          }
+        }
+      ]
+    }
+  }
+}