From 0585be648f80cdf0278a2a8f68633f51e61e0f4a Mon Sep 17 00:00:00 2001 From: waldronmatt Date: Sun, 1 Sep 2024 12:04:25 -0400 Subject: [PATCH] docs(lit-override): added notes, minor fixes --- apps/lit-override/src/ts/shadow-dom.ts | 2 +- packages/lit-override/custom-elements.json | 288 +++++++++--------- packages/lit-override/custom-elements.md | 120 ++++---- .../src/decorators/query-template-by-id.ts | 1 + 4 files changed, 206 insertions(+), 205 deletions(-) diff --git a/apps/lit-override/src/ts/shadow-dom.ts b/apps/lit-override/src/ts/shadow-dom.ts index 0b2ebffe..866fc2d2 100644 --- a/apps/lit-override/src/ts/shadow-dom.ts +++ b/apps/lit-override/src/ts/shadow-dom.ts @@ -23,7 +23,7 @@ export class HostApp extends LitElement { private renderMarkupOverride() { const message = 'Hello world'; return html` -

Templating support from lit-html: ${message}

+

Templating support from lit-html: ${message}!

`; diff --git a/packages/lit-override/custom-elements.json b/packages/lit-override/custom-elements.json index f6579777..766623e1 100644 --- a/packages/lit-override/custom-elements.json +++ b/packages/lit-override/custom-elements.json @@ -75,6 +75,107 @@ "declarations": [], "exports": [] }, + { + "kind": "javascript-module", + "path": "src/controllers/adopted-stylesheets-converter.ts", + "declarations": [ + { + "kind": "class", + "description": "AdoptedStyleSheetsConverter\n\nDetects a `style` tag inside a `template` element from the light DOM, converts the styles,\nand adds it to the component's `adoptedStyleSheets`.", + "name": "AdoptedStyleSheetsConverter", + "members": [ + { + "kind": "field", + "name": "host", + "type": { + "text": "ReactiveControllerHost" + }, + "default": "host" + }, + { + "kind": "field", + "name": "clearStyles", + "type": { + "text": "AdoptedStyleSheetsConverterParams['clearStyles']" + }, + "default": "clearStyles" + }, + { + "kind": "field", + "name": "templateEl", + "type": { + "text": "AdoptedStyleSheetsConverterParams['templateEl']" + }, + "default": "templateEl" + }, + { + "kind": "field", + "name": "_shadowRoot", + "type": { + "text": "ShadowRoot" + }, + "default": "(this.host as LitElement).renderRoot" + }, + { + "kind": "method", + "name": "hostConnected" + }, + { + "kind": "method", + "name": "hostUpdated" + }, + { + "kind": "method", + "name": "updateStylesheet", + "privacy": "private" + }, + { + "kind": "method", + "name": "setAdoptedStyleSheets", + "privacy": "private", + "parameters": [ + { + "name": "styleElement", + "type": { + "text": "HTMLStyleElement" + } + } + ] + }, + { + "kind": "method", + "name": "removeComponentStyleTag", + "privacy": "private" + } + ] + } + ], + "exports": [ + { + "kind": "js", + "name": "AdoptedStyleSheetsConverter", + "declaration": { + "name": "AdoptedStyleSheetsConverter", + "module": "src/controllers/adopted-stylesheets-converter.ts" + } + } + ] + }, + { + "kind": "javascript-module", + "path": "src/controllers/index.ts", + "declarations": [], + "exports": [ + { + "kind": "js", + "name": "*", + "declaration": { + "name": "*", + "package": "./adopted-stylesheets-converter.js" + } + } + ] + }, { "kind": "javascript-module", "path": "src/components/index.ts", @@ -228,7 +329,7 @@ }, { "kind": "javascript-module", - "path": "src/decorators/index.ts", + "path": "src/directives/index.ts", "declarations": [], "exports": [ { @@ -236,116 +337,37 @@ "name": "*", "declaration": { "name": "*", - "package": "./query-template-by-id.js" + "package": "./template-content-with-fallback.js" } } ] }, { "kind": "javascript-module", - "path": "src/decorators/query-template-by-id.ts", + "path": "src/directives/template-content-with-fallback.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": "class", + "description": "", + "name": "TemplateContentWithFallbackDirective", + "members": [], + "superclass": { + "name": "Directive", + "package": "lit/directive.js" } - } - ] - }, - { - "kind": "javascript-module", - "path": "src/controllers/adopted-stylesheets-converter.ts", - "declarations": [ + }, { - "kind": "class", - "description": "AdoptedStyleSheetsConverter\n\nDetects a `style` tag inside a `template` element from the light DOM, converts the styles,\nand adds it to the component's `adoptedStyleSheets`.", - "name": "AdoptedStyleSheetsConverter", - "members": [ - { - "kind": "field", - "name": "host", - "type": { - "text": "ReactiveControllerHost" - }, - "default": "host" - }, - { - "kind": "field", - "name": "clearStyles", - "type": { - "text": "AdoptedStyleSheetsConverterParams['clearStyles']" - }, - "default": "clearStyles" - }, - { - "kind": "field", - "name": "templateEl", - "type": { - "text": "AdoptedStyleSheetsConverterParams['templateEl']" - }, - "default": "templateEl" - }, - { - "kind": "field", - "name": "_shadowRoot", - "type": { - "text": "ShadowRoot" - }, - "default": "(this.host as LitElement).renderRoot" - }, - { - "kind": "method", - "name": "hostConnected" - }, - { - "kind": "method", - "name": "hostUpdated" - }, - { - "kind": "method", - "name": "updateStylesheet", - "privacy": "private" - }, + "kind": "variable", + "name": "templateContentWithFallback", + "description": "TemplateContentWithFallbackDirective\n\nDetects a `template` element from the light DOM and renders it.\nWill fallback to your component's markup provided as an argument.", + "parameters": [ { - "kind": "method", - "name": "setAdoptedStyleSheets", - "privacy": "private", - "parameters": [ - { - "name": "styleElement", - "type": { - "text": "HTMLStyleElement" - } - } - ] + "description": "renders markup if a `template` element is not found. Defaults to ``.", + "name": "fallback" }, { - "kind": "method", - "name": "removeComponentStyleTag", - "privacy": "private" + "description": "a `template` element. Defaults to null.", + "name": "templateEl" } ] } @@ -353,32 +375,25 @@ "exports": [ { "kind": "js", - "name": "AdoptedStyleSheetsConverter", + "name": "templateContentWithFallback", "declaration": { - "name": "AdoptedStyleSheetsConverter", - "module": "src/controllers/adopted-stylesheets-converter.ts" + "name": "templateContentWithFallback", + "module": "src/directives/template-content-with-fallback.ts" } - } - ] - }, - { - "kind": "javascript-module", - "path": "src/controllers/index.ts", - "declarations": [], - "exports": [ + }, { "kind": "js", - "name": "*", + "name": "TemplateContentWithFallbackDirective", "declaration": { - "name": "*", - "package": "./adopted-stylesheets-converter.js" + "name": "TemplateContentWithFallbackDirective", + "module": "src/directives/template-content-with-fallback.ts" } } ] }, { "kind": "javascript-module", - "path": "src/directives/index.ts", + "path": "src/decorators/index.ts", "declarations": [], "exports": [ { @@ -386,56 +401,41 @@ "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": [], - "superclass": { - "name": "Directive", - "package": "lit/directive.js" - } - }, - { - "kind": "variable", - "name": "templateContentWithFallback", - "description": "TemplateContentWithFallbackDirective\n\nDetects a `template` element from the light DOM and renders it.\nWill fallback to your component's markup provided as an argument.", + "kind": "function", + "name": "queryTemplateById", "parameters": [ { - "description": "renders markup if a `template` element is not found. Defaults to ``.", - "name": "fallback" + "name": "{ fallback = false }", + "default": "{}", + "type": { + "text": "QueryTemplateByIdParams" + } }, { - "description": "a `template` element. Defaults to null.", - "name": "templateEl" + "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": "templateContentWithFallback", - "declaration": { - "name": "templateContentWithFallback", - "module": "src/directives/template-content-with-fallback.ts" - } - }, - { - "kind": "js", - "name": "TemplateContentWithFallbackDirective", + "name": "queryTemplateById", "declaration": { - "name": "TemplateContentWithFallbackDirective", - "module": "src/directives/template-content-with-fallback.ts" + "name": "queryTemplateById", + "module": "src/decorators/query-template-by-id.ts" } } ] diff --git a/packages/lit-override/custom-elements.md b/packages/lit-override/custom-elements.md index f3c73e06..373078e5 100644 --- a/packages/lit-override/custom-elements.md +++ b/packages/lit-override/custom-elements.md @@ -11,6 +11,45 @@ | `js` | `*` | \* | | ./mixins/index.js | | `js` | `*` | \* | | ./utils/index.js | +## `src/controllers/adopted-stylesheets-converter.ts`: + +### class: `AdoptedStyleSheetsConverter` + +#### Fields + +| Name | Privacy | Type | Default | Description | Inherited From | +| ------------- | ------- | -------------------------------------------------- | -------------------------------------- | ----------- | -------------- | +| `host` | | `ReactiveControllerHost` | `host` | | | +| `clearStyles` | | `AdoptedStyleSheetsConverterParams['clearStyles']` | `clearStyles` | | | +| `templateEl` | | `AdoptedStyleSheetsConverterParams['templateEl']` | `templateEl` | | | +| `_shadowRoot` | | `ShadowRoot` | `(this.host as LitElement).renderRoot` | | | + +#### Methods + +| Name | Privacy | Description | Parameters | Return | Inherited From | +| ------------------------- | ------- | ----------- | -------------------------------- | ------ | -------------- | +| `hostConnected` | | | | | | +| `hostUpdated` | | | | | | +| `updateStylesheet` | private | | | | | +| `setAdoptedStyleSheets` | private | | `styleElement: HTMLStyleElement` | | | +| `removeComponentStyleTag` | private | | | | | + +
+ +### Exports + +| Kind | Name | Declaration | Module | Package | +| ---- | ----------------------------- | --------------------------- | ------------------------------------------------ | ------- | +| `js` | `AdoptedStyleSheetsConverter` | AdoptedStyleSheetsConverter | src/controllers/adopted-stylesheets-converter.ts | | + +## `src/controllers/index.ts`: + +### Exports + +| Kind | Name | Declaration | Module | Package | +| ---- | ---- | ----------- | ------ | ---------------------------------- | +| `js` | `*` | \* | | ./adopted-stylesheets-converter.js | + ## `src/components/index.ts`: ### Exports @@ -74,6 +113,27 @@ | `js` | `default` | LitOverride | src/components/lit-override.ts | | | `custom-element-definition` | `lit-override` | LitOverride | /src/components/lit-override-component.js | | +## `src/directives/index.ts`: + +### Exports + +| Kind | Name | Declaration | Module | Package | +| ---- | ---- | ----------- | ------ | ----------------------------------- | +| `js` | `*` | \* | | ./template-content-with-fallback.js | + +## `src/directives/template-content-with-fallback.ts`: + +### class: `TemplateContentWithFallbackDirective` + +
+ +### 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 | | + ## `src/decorators/index.ts`: ### Exports @@ -98,66 +158,6 @@ | ---- | ------------------- | ----------------- | -------------------------------------- | ------- | | `js` | `queryTemplateById` | queryTemplateById | src/decorators/query-template-by-id.ts | | -## `src/controllers/adopted-stylesheets-converter.ts`: - -### class: `AdoptedStyleSheetsConverter` - -#### Fields - -| Name | Privacy | Type | Default | Description | Inherited From | -| ------------- | ------- | -------------------------------------------------- | -------------------------------------- | ----------- | -------------- | -| `host` | | `ReactiveControllerHost` | `host` | | | -| `clearStyles` | | `AdoptedStyleSheetsConverterParams['clearStyles']` | `clearStyles` | | | -| `templateEl` | | `AdoptedStyleSheetsConverterParams['templateEl']` | `templateEl` | | | -| `_shadowRoot` | | `ShadowRoot` | `(this.host as LitElement).renderRoot` | | | - -#### Methods - -| Name | Privacy | Description | Parameters | Return | Inherited From | -| ------------------------- | ------- | ----------- | -------------------------------- | ------ | -------------- | -| `hostConnected` | | | | | | -| `hostUpdated` | | | | | | -| `updateStylesheet` | private | | | | | -| `setAdoptedStyleSheets` | private | | `styleElement: HTMLStyleElement` | | | -| `removeComponentStyleTag` | private | | | | | - -
- -### Exports - -| Kind | Name | Declaration | Module | Package | -| ---- | ----------------------------- | --------------------------- | ------------------------------------------------ | ------- | -| `js` | `AdoptedStyleSheetsConverter` | AdoptedStyleSheetsConverter | src/controllers/adopted-stylesheets-converter.ts | | - -## `src/controllers/index.ts`: - -### Exports - -| Kind | Name | Declaration | Module | Package | -| ---- | ---- | ----------- | ------ | ---------------------------------- | -| `js` | `*` | \* | | ./adopted-stylesheets-converter.js | - -## `src/directives/index.ts`: - -### Exports - -| Kind | Name | Declaration | Module | Package | -| ---- | ---- | ----------- | ------ | ----------------------------------- | -| `js` | `*` | \* | | ./template-content-with-fallback.js | - -## `src/directives/template-content-with-fallback.ts`: - -### class: `TemplateContentWithFallbackDirective` - -
- -### 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 | | - ## `src/mixins/emit-connected-callback.ts`: ### class: `EmitConnectedCallbackProps` 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 c7d0425b..27cc2c88 100644 --- a/packages/lit-override/src/decorators/query-template-by-id.ts +++ b/packages/lit-override/src/decorators/query-template-by-id.ts @@ -25,6 +25,7 @@ export interface QueryTemplateByIdParams { */ export const queryTemplateById = ({ fallback = false }: QueryTemplateByIdParams = {}) => { return (proto: T, propName: string) => { + // this is a 'wrapper' around a custom property accessor: https://lit.dev/docs/components/properties/#accessors const internalKey = Symbol(`_${String(propName)}`); property({ reflect: true, type: String })(proto, propName);