feat(lit-override): add custom decorator to get template element by id

waldronmatt · Aug 31, 2024 · 6a07702 · 6a07702
1 parent 9d5415f
commit 6a07702
Show file tree

Hide file tree

Showing 16 changed files with 288 additions and 198 deletions.
diff --git a/apps/lit-override/src/html/markup-light-dom.html b/apps/lit-override/src/html/markup-light-dom.html
@@ -12,11 +12,11 @@
     </template>
     <h1>Markup slotted from the light dom and styles applied by the host app!</h1>
     <host-app>
-      <child-component id="childTemplate">
+      <child-component templateId="childTemplate">
         <h3 slot="heading">A child component heading from a template in the <em>light dom</em>!</h3>
         <p slot="sub-heading">A child component paragraph from a template in the <em>light dom</em>.</p>
       </child-component>
-      <lit-override id="childTemplate">
+      <lit-override templateId="childTemplate">
         <h3 slot="heading">A lit override component heading from a template in the <em>light dom</em>!</h3>
         <p slot="sub-heading">A lit override component paragraph from a template in the <em>light dom</em>.</p>
       </lit-override>

diff --git a/apps/lit-override/src/html/styles-light-dom.html b/apps/lit-override/src/html/styles-light-dom.html
@@ -25,11 +25,11 @@
     </template>
     <h1>Styles slotted from the light dom and markup applied by the host app!</h1>
     <host-app>
-      <child-component id="childTemplate">
+      <child-component templateId="childTemplate">
         <h3 slot="heading">A child component heading from a Lit template in the <em>host app</em>!</h3>
         <p slot="sub-heading">A child component paragraph from a Lit template in the <em>host app</em>.</p>
       </child-component>
-      <lit-override id="childTemplate">
+      <lit-override templateId="childTemplate">
         <h3 slot="heading">A lit override component heading from a Lit template in the <em>host app</em>!</h3>
         <p slot="sub-heading">A lit override component paragraph from a Lit template in the <em>host app</em>.</p>
       </lit-override>

diff --git a/apps/lit-override/src/ts/child-component.ts b/apps/lit-override/src/ts/child-component.ts
@@ -1,8 +1,8 @@
 import { LitElement, css, html } from 'lit';
-import { property } from 'lit/decorators.js';
 import { EmitConnectedCallback } from '@waldronmatt/lit-override/src/mixins/index.js';
 import { templateContentWithFallback } from '@waldronmatt/lit-override/src/directives/index.js';
 import { AdoptedStyleSheetsConverter } from '@waldronmatt/lit-override/src/controllers/index.js';
+import { queryTemplateById } from '@waldronmatt/lit-override/src/decorators/index.js';
 
 export class ChildComponent extends EmitConnectedCallback(LitElement) {
   static styles = css`
@@ -17,12 +17,12 @@ export class ChildComponent extends EmitConnectedCallback(LitElement) {
     }
   `;
 
-  @property({ reflect: true, type: String })
-  templateId!: string;
+  @queryTemplateById()
+  templateId!: HTMLTemplateElement | null;
 
   connectedCallback() {
     super.connectedCallback();
-    new AdoptedStyleSheetsConverter(this, { id: this.templateId });
+    new AdoptedStyleSheetsConverter(this, { templateEl: this.templateId });
   }
 
   markup() {
@@ -34,7 +34,7 @@ export class ChildComponent extends EmitConnectedCallback(LitElement) {
   }
 
   protected render() {
-    return html`${templateContentWithFallback({ fallback: this.markup(), id: this.templateId })}`;
+    return html`${templateContentWithFallback({ fallback: this.markup(), templateEl: this.templateId })}`;
   }
 }
 

diff --git a/apps/lit-override/src/ts/lazy-load.ts b/apps/lit-override/src/ts/lazy-load.ts
@@ -5,11 +5,11 @@ document.getElementById('load-component')?.addEventListener('click', () => {
     const container = document.getElementById('component-container');
     const component = document.createElement('host-app');
     component.innerHTML = `
-      <child-component id="childTemplate">
+      <child-component templateId="childTemplate">
         <h3 slot="heading">A heading from a template in the <em>light dom</em>!</h3>
         <p slot="sub-heading">A paragraph from a template in the <em>light dom</em>.</p>
       </child-component>
-      <lit-override id="childTemplate">
+      <lit-override templateId="childTemplate">
         <h3 slot="heading">A heading from a template in the <em>light dom</em>!</h3>
         <p slot="sub-heading">A paragraph from a template in the <em>light dom</em>.</p>
       </lit-override>

diff --git a/packages/lit-override/README.md b/packages/lit-override/README.md
@@ -83,18 +83,27 @@ import { LitElement, html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { templateContentWithFallback } from '@waldronmatt/lit-override/directives/template-content-with-fallback.js';
 import { AdoptedStyleSheetsConverter } from '@waldronmatt/lit-override/controllers/adopted-stylesheets-converter.js';
+import { queryTemplateById } from '@waldronmatt/lit-override/decorators/query-template-by-id.js';
 
 export class ChildComponent extends LitElement {
-  @property({ reflect: true, type: String })
-  templateId!: string;
+  @queryTemplateById({ fallback: true })
+  templateId!: HTMLTemplateElement | null;
 
   connectedCallback() {
     super.connectedCallback();
-    new AdoptedStyleSheetsConverter(this, { id: this.templateId });
+    new AdoptedStyleSheetsConverter(this, {
+      clearStyes: true,
+      templateEl: this.templateId,
+    });
   }
 
   protected render() {
-    return html`${templateContentWithFallback({ fallback: html`<p>Default markup</p>`, id: this.templateId })}`;
+    return html`
+      ${templateContentWithFallback({
+        fallback: html`<p>Default markup</p>`,
+        templateEl: this.templateId,
+      })}
+    `;
   }
 }
 ```

diff --git a/packages/lit-override/custom-elements.json b/packages/lit-override/custom-elements.json
@@ -23,6 +23,14 @@
             "package": "./controllers/index.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./decorators/index.js"
+          }
+        },
         {
           "kind": "js",
           "name": "*",
@@ -101,10 +109,8 @@
               "kind": "field",
               "name": "templateId",
               "type": {
-                "text": "string"
-              },
-              "attribute": "templateId",
-              "reflects": true
+                "text": "HTMLTemplateElement | null"
+              }
             },
             {
               "kind": "field",
@@ -149,14 +155,19 @@
               "name": "connected-callback"
             }
           ],
-          "attributes": [
+          "mixins": [
             {
-              "name": "templateId",
-              "type": {
-                "text": "string"
-              },
-              "fieldName": "templateId"
-            },
+              "name": "EmitConnectedCallback",
+              "module": "/src/mixins/emit-connected-callback.js"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "lit-override",
+          "customElement": true,
+          "attributes": [
             {
               "name": "emitConnectedCallback",
               "type": {
@@ -177,19 +188,7 @@
                 "module": "src/mixins/emit-connected-callback.ts"
               }
             }
-          ],
-          "mixins": [
-            {
-              "name": "EmitConnectedCallback",
-              "module": "/src/mixins/emit-connected-callback.js"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "lit-override",
-          "customElement": true
+          ]
         }
       ],
       "exports": [
@@ -253,28 +252,27 @@
             },
             {
               "kind": "field",
-              "name": "_template",
+              "name": "clearStyles",
               "type": {
-                "text": "HTMLTemplateElement | null"
+                "text": "AdoptedStyleSheetsConverterParams['clearStyles']"
               },
-              "privacy": "private",
-              "default": "null"
+              "default": "clearStyles"
             },
             {
               "kind": "field",
-              "name": "clearStyles",
+              "name": "templateEl",
               "type": {
-                "text": "boolean"
+                "text": "AdoptedStyleSheetsConverterParams['templateEl']"
               },
-              "default": "clearStyles"
+              "default": "templateEl"
             },
             {
               "kind": "field",
-              "name": "id",
+              "name": "_shadowRoot",
               "type": {
-                "text": "string"
+                "text": "ShadowRoot"
               },
-              "default": "id"
+              "default": "(this.host as LitElement).renderRoot"
             },
             {
               "kind": "method",
@@ -286,22 +284,12 @@
             },
             {
               "kind": "method",
-              "name": "getTemplateElement",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "HTMLTemplateElement | null"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "removeComponentStyleTag",
+              "name": "updateStylesheet",
               "privacy": "private"
             },
             {
               "kind": "method",
-              "name": "handleAdoptedStyleSheets",
+              "name": "setAdoptedStyleSheets",
               "privacy": "private",
               "parameters": [
                 {
@@ -314,7 +302,7 @@
             },
             {
               "kind": "method",
-              "name": "updateStylesheet",
+              "name": "removeComponentStyleTag",
               "privacy": "private"
             }
           ]
@@ -348,56 +336,77 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/directives/index.ts",
+      "path": "src/decorators/index.ts",
       "declarations": [],
       "exports": [
         {
           "kind": "js",
           "name": "*",
           "declaration": {
             "name": "*",
-            "package": "./template-content-with-fallback.js"
+            "package": "./query-template-by-id.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/directives/template-content-with-fallback.ts",
+      "path": "src/decorators/query-template-by-id.ts",
       "declarations": [
         {
-          "kind": "class",
-          "description": "",
-          "name": "TemplateContentWithFallbackDirective",
-          "members": [
+          "kind": "function",
+          "name": "queryTemplateById",
+          "parameters": [
             {
-              "kind": "field",
-              "name": "_template",
+              "name": "{ fallback = false }",
+              "default": "{}",
               "type": {
-                "text": "HTMLTemplateElement | null"
-              },
-              "privacy": "private",
-              "default": "null"
+                "text": "{ fallback?: boolean }"
+              }
             },
             {
-              "kind": "method",
-              "name": "getTemplateElement",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "HTMLTemplateElement | null"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "id",
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ]
+              "description": "gets a template element if an id is not provided (not cached). Defaults to `false`.",
+              "name": "fallback"
             }
           ],
+          "description": "queryTemplateById\n\nGets a template element by id that is provided to the `templateId` property.\nWill cache the template element on successful query."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "queryTemplateById",
+          "declaration": {
+            "name": "queryTemplateById",
+            "module": "src/decorators/query-template-by-id.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/directives/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./template-content-with-fallback.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/directives/template-content-with-fallback.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "TemplateContentWithFallbackDirective",
+          "members": [],
           "superclass": {
             "name": "Directive",
             "package": "lit/directive.js"
@@ -413,8 +422,8 @@
               "name": "fallback"
             },
             {
-              "description": "unique identifier that points to the id of a `template` element. Defaults to empty string.",
-              "name": "id"
+              "description": "a `template` element. Defaults to null.",
+              "name": "templateEl"
             }
           ]
         }
@@ -583,7 +592,7 @@
               "type": {
                 "text": "TemplateResult"
               },
-              "description": "TemplateResult\n\n**Note**: Only static markdown is supported."
+              "description": "TemplateResult"
             }
           ],
           "description": "Applies the given template to the `shadowRoot` of elements."