From e7ec054cfdaa93262fe35963072d8d0f3814668e Mon Sep 17 00:00:00 2001
From: waldronmatt <mhuntwaldron@gmail.com>
Date: Sat, 31 Aug 2024 22:06:29 -0400
Subject: [PATCH] fix(lit-override): add decorator interface, naming cleanup,
 add const in markup example

---
 apps/lit-override/src/ts/shadow-dom.ts        |   2 +
 packages/lit-override/custom-elements.json    | 115 ++++++++----------
 packages/lit-override/custom-elements.md      |  69 ++++++-----
 .../src/components/lit-override-component.ts  |   6 +-
 .../src/decorators/query-template-by-id.ts    |  10 +-
 .../src/mixins/emit-connected-callback.ts     |   2 +-
 6 files changed, 101 insertions(+), 103 deletions(-)

diff --git a/apps/lit-override/src/ts/shadow-dom.ts b/apps/lit-override/src/ts/shadow-dom.ts
index 446728fa..0b2ebffe 100644
--- a/apps/lit-override/src/ts/shadow-dom.ts
+++ b/apps/lit-override/src/ts/shadow-dom.ts
@@ -21,7 +21,9 @@ export class HostApp extends LitElement {
   `;
 
   private renderMarkupOverride() {
+    const message = 'Hello world';
     return html`
+      <p>Templating support from lit-html: ${message}</p>
       <slot name="heading"></slot>
       <slot name="sub-heading"></slot>
     `;
diff --git a/packages/lit-override/custom-elements.json b/packages/lit-override/custom-elements.json
index 48b7cc55..ba7695ab 100644
--- a/packages/lit-override/custom-elements.json
+++ b/packages/lit-override/custom-elements.json
@@ -100,7 +100,7 @@
           "name": "LitOverride",
           "slots": [
             {
-              "description": "is rendered as fallback if `<template>` element is not found",
+              "description": "is rendered as fallback if `<template>` element is not found.",
               "name": "`<slot></slot>`"
             }
           ],
@@ -109,8 +109,9 @@
               "kind": "field",
               "name": "templateId",
               "type": {
-                "text": "HTMLTemplateElement | null"
-              }
+                "text": "string"
+              },
+              "description": "Set an id referencing a `template` element. Defaults to a generic `template` element."
             },
             {
               "kind": "field",
@@ -139,19 +140,11 @@
                 "name": "EmitConnectedCallback",
                 "module": "src/mixins/emit-connected-callback.ts"
               }
-            },
-            {
-              "type": {
-                "text": "string"
-              },
-              "description": "unique identifier that points to the id of a `template` element. Defaults to empty string.",
-              "name": "id",
-              "kind": "field"
             }
           ],
           "events": [
             {
-              "description": "when `emitConnectedCallback` is `true`",
+              "description": "when `emitConnectedCallback` is `true`.",
               "name": "connected-callback"
             }
           ],
@@ -334,55 +327,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/decorators/index.ts",
-      "declarations": [],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "*",
-          "declaration": {
-            "name": "*",
-            "package": "./query-template-by-id.js"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/decorators/query-template-by-id.ts",
-      "declarations": [
-        {
-          "kind": "function",
-          "name": "queryTemplateById",
-          "parameters": [
-            {
-              "name": "{ fallback = false }",
-              "default": "{}",
-              "type": {
-                "text": "{ fallback?: boolean }"
-              }
-            },
-            {
-              "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",
@@ -447,6 +391,55 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/decorators/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./query-template-by-id.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/decorators/query-template-by-id.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "queryTemplateById",
+          "parameters": [
+            {
+              "name": "{ fallback = false }",
+              "default": "{}",
+              "type": {
+                "text": "QueryTemplateByIdParams"
+              }
+            },
+            {
+              "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/mixins/emit-connected-callback.ts",
diff --git a/packages/lit-override/custom-elements.md b/packages/lit-override/custom-elements.md
index d0fcd06c..7582b7cb 100644
--- a/packages/lit-override/custom-elements.md
+++ b/packages/lit-override/custom-elements.md
@@ -31,18 +31,17 @@
 
 #### Fields
 
-| Name                    | Privacy | Type                          | Default | Description                                                                                  | Inherited From        |
-| ----------------------- | ------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------- | --------------------- |
-| `templateId`            |         | `HTMLTemplateElement \| null` |         |                                                                                              |                       |
-| `emitConnectedCallback` |         | `boolean`                     | `false` | Set prop to use \`connected-callback\` event. Defaults to \`false\`.                         | EmitConnectedCallback |
-| `onConnectedCallback`   |         | `function`                    |         | A callback function called when connected to the DOM.                                        | EmitConnectedCallback |
-| `id`                    |         | `string`                      |         | unique identifier that points to the id of a \`template\` element. Defaults to empty string. |                       |
+| Name                    | Privacy | Type       | Default | Description                                                                               | Inherited From        |
+| ----------------------- | ------- | ---------- | ------- | ----------------------------------------------------------------------------------------- | --------------------- |
+| `templateId`            |         | `string`   |         | Set an id referencing a \`template\` element. Defaults to a generic \`template\` element. |                       |
+| `emitConnectedCallback` |         | `boolean`  | `false` | Set prop to use \`connected-callback\` event. Defaults to \`false\`.                      | EmitConnectedCallback |
+| `onConnectedCallback`   |         | `function` |         | A callback function called when connected to the DOM.                                     | EmitConnectedCallback |
 
 #### Events
 
-| Name                 | Type | Description                                | Inherited From |
-| -------------------- | ---- | ------------------------------------------ | -------------- |
-| `connected-callback` |      | when \`emitConnectedCallback\` is \`true\` |                |
+| Name                 | Type | Description                                 | Inherited From |
+| -------------------- | ---- | ------------------------------------------- | -------------- |
+| `connected-callback` |      | when \`emitConnectedCallback\` is \`true\`. |                |
 
 #### Attributes
 
@@ -53,9 +52,9 @@
 
 #### Slots
 
-| Name                  | Description                                                     |
-| --------------------- | --------------------------------------------------------------- |
-| `` `<slot></slot>` `` | is rendered as fallback if \`\<template>\` element is not found |
+| Name                  | Description                                                      |
+| --------------------- | ---------------------------------------------------------------- |
+| `` `<slot></slot>` `` | is rendered as fallback if \`\<template>\` element is not found. |
 
 <hr/>
 
@@ -114,50 +113,50 @@
 | ---- | ---- | ----------- | ------ | ---------------------------------- |
 | `js` | `*`  | \*          |        | ./adopted-stylesheets-converter.js |
 
-## `src/decorators/index.ts`:
+## `src/directives/index.ts`:
 
 ### Exports
 
-| Kind | Name | Declaration | Module | Package                   |
-| ---- | ---- | ----------- | ------ | ------------------------- |
-| `js` | `*`  | \*          |        | ./query-template-by-id.js |
-
-## `src/decorators/query-template-by-id.ts`:
+| Kind | Name | Declaration | Module | Package                             |
+| ---- | ---- | ----------- | ------ | ----------------------------------- |
+| `js` | `*`  | \*          |        | ./template-content-with-fallback.js |
 
-### Functions
+## `src/directives/template-content-with-fallback.ts`:
 
-| Name                | Description                                                                                                                                                        | Parameters                                               | Return |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | ------ |
-| `queryTemplateById` | queryTemplateById&#xA;&#xA;Gets a template element by id that is provided to the \`templateId\` property.&#xA;Will cache the template element on successful query. | `{ fallback = false }: { fallback?: boolean }, fallback` |        |
+### class: `TemplateContentWithFallbackDirective`
 
 <hr/>
 
 ### Exports
 
-| Kind | Name                | Declaration       | Module                                 | Package |
-| ---- | ------------------- | ----------------- | -------------------------------------- | ------- |
-| `js` | `queryTemplateById` | queryTemplateById | src/decorators/query-template-by-id.ts |         |
+| Kind | Name                                   | Declaration                          | Module                                           | Package |
+| ---- | -------------------------------------- | ------------------------------------ | ------------------------------------------------ | ------- |
+| `js` | `templateContentWithFallback`          | templateContentWithFallback          | src/directives/template-content-with-fallback.ts |         |
+| `js` | `TemplateContentWithFallbackDirective` | TemplateContentWithFallbackDirective | src/directives/template-content-with-fallback.ts |         |
 
-## `src/directives/index.ts`:
+## `src/decorators/index.ts`:
 
 ### Exports
 
-| Kind | Name | Declaration | Module | Package                             |
-| ---- | ---- | ----------- | ------ | ----------------------------------- |
-| `js` | `*`  | \*          |        | ./template-content-with-fallback.js |
+| Kind | Name | Declaration | Module | Package                   |
+| ---- | ---- | ----------- | ------ | ------------------------- |
+| `js` | `*`  | \*          |        | ./query-template-by-id.js |
 
-## `src/directives/template-content-with-fallback.ts`:
+## `src/decorators/query-template-by-id.ts`:
 
-### class: `TemplateContentWithFallbackDirective`
+### Functions
+
+| Name                | Description                                                                                                                                                        | Parameters                                                | Return |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | ------ |
+| `queryTemplateById` | queryTemplateById&#xA;&#xA;Gets a template element by id that is provided to the \`templateId\` property.&#xA;Will cache the template element on successful query. | `{ fallback = false }: QueryTemplateByIdParams, fallback` |        |
 
 <hr/>
 
 ### Exports
 
-| Kind | Name                                   | Declaration                          | Module                                           | Package |
-| ---- | -------------------------------------- | ------------------------------------ | ------------------------------------------------ | ------- |
-| `js` | `templateContentWithFallback`          | templateContentWithFallback          | src/directives/template-content-with-fallback.ts |         |
-| `js` | `TemplateContentWithFallbackDirective` | TemplateContentWithFallbackDirective | src/directives/template-content-with-fallback.ts |         |
+| Kind | Name                | Declaration       | Module                                 | Package |
+| ---- | ------------------- | ----------------- | -------------------------------------- | ------- |
+| `js` | `queryTemplateById` | queryTemplateById | src/decorators/query-template-by-id.ts |         |
 
 ## `src/mixins/emit-connected-callback.ts`:
 
diff --git a/packages/lit-override/src/components/lit-override-component.ts b/packages/lit-override/src/components/lit-override-component.ts
index 783703ee..437949ab 100644
--- a/packages/lit-override/src/components/lit-override-component.ts
+++ b/packages/lit-override/src/components/lit-override-component.ts
@@ -9,11 +9,11 @@ import { queryTemplateById } from '../decorators/query-template-by-id.js';
  *
  * A shell component for overriding styles and markup.
  *
- * @fires connected-callback when `emitConnectedCallback` is `true`
+ * @fires connected-callback when `emitConnectedCallback` is `true`.
  * @property {boolean} emitConnectedCallback - Set prop to use `connected-callback` event. Defaults to `false`.
  * @property {function} onConnectedCallback - A callback function called when connected to the DOM.
- * @property {string} id - unique identifier that points to the id of a `template` element. Defaults to empty string.
- * @slot `<slot></slot>` is rendered as fallback if `<template>` element is not found
+ * @property {string} templateId - Set an id referencing a `template` element. Defaults to a generic `template` element.
+ * @slot `<slot></slot>` is rendered as fallback if `<template>` element is not found.
  */
 export class LitOverride extends EmitConnectedCallback(LitElement) {
   @queryTemplateById({ fallback: true })
diff --git a/packages/lit-override/src/decorators/query-template-by-id.ts b/packages/lit-override/src/decorators/query-template-by-id.ts
index 5e7ccb3a..928c62c0 100644
--- a/packages/lit-override/src/decorators/query-template-by-id.ts
+++ b/packages/lit-override/src/decorators/query-template-by-id.ts
@@ -1,11 +1,15 @@
 import { property } from 'lit/decorators.js';
 import { ReactiveElement } from 'lit';
 
-export interface ExtendedElement extends ReactiveElement {
+interface ExtendedElement extends ReactiveElement {
   [key: symbol]: string | null;
   _templateCache?: Record<string, HTMLTemplateElement | null>;
 }
 
+export interface QueryTemplateByIdParams {
+  fallback?: boolean;
+}
+
 /**
  * queryTemplateById
  *
@@ -14,7 +18,7 @@ export interface ExtendedElement extends ReactiveElement {
  *
  * @param fallback gets a template element if an id is not provided (not cached). Defaults to `false`.
  */
-export const queryTemplateById = ({ fallback = false }: { fallback?: boolean } = {}) => {
+export const queryTemplateById = ({ fallback = false }: QueryTemplateByIdParams = {}) => {
   return <T extends ReactiveElement>(proto: T, propName: string) => {
     const internalKey = Symbol(`_${String(propName)}`);
 
@@ -44,7 +48,7 @@ export const queryTemplateById = ({ fallback = false }: { fallback?: boolean } =
           return templateElement;
         }
 
-        return fallback ? (document.querySelector('template') as HTMLTemplateElement | null) : null;
+        return fallback ? document.querySelector('template') : null;
       },
       set(this: ExtendedElement, value: string | null) {
         this[internalKey] = value;
diff --git a/packages/lit-override/src/mixins/emit-connected-callback.ts b/packages/lit-override/src/mixins/emit-connected-callback.ts
index 169c30bd..6290b003 100644
--- a/packages/lit-override/src/mixins/emit-connected-callback.ts
+++ b/packages/lit-override/src/mixins/emit-connected-callback.ts
@@ -19,7 +19,7 @@ export declare class EmitConnectedCallbackProps {
  * Enables your component to emit `connected-callback` if `emitConnectedCallback` prop is set.
  * Alternatively, use `onConnectedCallback` if performance is a concern.
  *
- * @fires connected-callback when `emitConnectedCallback` is `true`
+ * @fires connected-callback when `emitConnectedCallback` is `true`.
  * @property {boolean} emitConnectedCallback - Set prop to use `connected-callback` event. Defaults to `false`.
  * @property {function} onConnectedCallback - A callback function called when connected to the DOM.
  */