From f9a1c99f5f70732b6cd74b78a8e1d8a778e284b2 Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 9 May 2022 11:12:17 -0700 Subject: [PATCH 1/6] Add `render` and `TemplateResult` documentation. --- packages/lit-html/src/lit-html.ts | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/packages/lit-html/src/lit-html.ts b/packages/lit-html/src/lit-html.ts index 11c23edc78..43ee5fe05a 100644 --- a/packages/lit-html/src/lit-html.ts +++ b/packages/lit-html/src/lit-html.ts @@ -443,7 +443,12 @@ const ELEMENT_PART = 6; const COMMENT_PART = 7; /** - * The return type of the template tag functions. + * The return type of the template tag functions, {@linkcode html} and + * {@linkcode svg}. + * + * This object captures the arguments passed into the tag function. A special + * array of strings that retain their identity between multiple evaluations of + * the tagged literal, and the values from the interpolated expressions. */ export type TemplateResult = { // This property needs to remain unminified. @@ -609,9 +614,24 @@ export interface RenderOptions { /** * Renders a value, usually a lit-html TemplateResult, to the container. - * @param value - * @param container - * @param options + * + * For example, to render "Hello, Zoe!" to the container `document.body`: + * + * ```js + * import {html, render} from 'lit'; + * + * const name = "Zoe"; + * render(html`

Hello, ${name}!

`, document.body); + * ``` + * + * @param value Any renderable value, typically a {@linkcode TemplateResult} + * created by evaluating a template tag like {@linkcode html} or + * {@linkcode svg}. + * @param container A DOM container to render to. The first render will append + * the rendered value to the container, and subsequent renders will + * efficiently update the rendered value if the same result type was + * previously rendered there. + * @param options See {@linkcode RenderOptions} for options documentation. */ export const render = ( value: unknown, From 49fb48e658d0e07148b57fa74dc536bb42890adc Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 9 May 2022 11:14:11 -0700 Subject: [PATCH 2/6] Add changeset --- .changeset/eighty-windows-bow.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/eighty-windows-bow.md diff --git a/.changeset/eighty-windows-bow.md b/.changeset/eighty-windows-bow.md new file mode 100644 index 0000000000..254c29a4ac --- /dev/null +++ b/.changeset/eighty-windows-bow.md @@ -0,0 +1,6 @@ +--- +'lit-html': patch +'lit': patch +--- + +Expand documentation for `render` and `TemplateResult`. From e276e501d57b6111e69dd88a6563baf52fee122a Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 9 May 2022 11:27:50 -0700 Subject: [PATCH 3/6] Add small amount of documentation to describe how to render a TemplateResult --- packages/lit-html/src/lit-html.ts | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/packages/lit-html/src/lit-html.ts b/packages/lit-html/src/lit-html.ts index 43ee5fe05a..72bb29be85 100644 --- a/packages/lit-html/src/lit-html.ts +++ b/packages/lit-html/src/lit-html.ts @@ -446,9 +446,14 @@ const COMMENT_PART = 7; * The return type of the template tag functions, {@linkcode html} and * {@linkcode svg}. * - * This object captures the arguments passed into the tag function. A special - * array of strings that retain their identity between multiple evaluations of - * the tagged literal, and the values from the interpolated expressions. + * The `TemplateResult` object captures the arguments passed into the tag + * function. A special array of strings that retain their identity between + * multiple evaluations of the tagged literal, and the values from the + * interpolated expressions. + * + * To create or update DOM from the `TemplateResult` you need to render the + * `TemplateResult`. See [Rendering](https://lit.dev/docs/components/rendering) + * for more information. */ export type TemplateResult = { // This property needs to remain unminified. From 4f27638679dedbb11151764ec1305383871294e2 Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 16 May 2022 12:06:23 -0700 Subject: [PATCH 4/6] Code review feedback --- packages/lit-html/src/lit-html.ts | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/packages/lit-html/src/lit-html.ts b/packages/lit-html/src/lit-html.ts index 72bb29be85..3174a5490c 100644 --- a/packages/lit-html/src/lit-html.ts +++ b/packages/lit-html/src/lit-html.ts @@ -446,14 +446,14 @@ const COMMENT_PART = 7; * The return type of the template tag functions, {@linkcode html} and * {@linkcode svg}. * - * The `TemplateResult` object captures the arguments passed into the tag - * function. A special array of strings that retain their identity between - * multiple evaluations of the tagged literal, and the values from the - * interpolated expressions. + * A `TemplateResult` object holds all the information about a template + * expression required to render it: the template strings, expression values, + * and type of template (html or svg). + * + * `TemplateResult` objects do not create any DOM on their own. To create or + * update DOM you need to render the `TemplateResult`. See + * [Rendering](https://lit.dev/docs/components/rendering) for more information. * - * To create or update DOM from the `TemplateResult` you need to render the - * `TemplateResult`. See [Rendering](https://lit.dev/docs/components/rendering) - * for more information. */ export type TemplateResult = { // This property needs to remain unminified. @@ -620,23 +620,26 @@ export interface RenderOptions { /** * Renders a value, usually a lit-html TemplateResult, to the container. * - * For example, to render "Hello, Zoe!" to the container `document.body`: + * For example, to render and create the DOM for the TemplateResult describing + * "

Hello!

" to the container `document.body`: * * ```js * import {html, render} from 'lit'; * - * const name = "Zoe"; - * render(html`

Hello, ${name}!

`, document.body); + * render(html`

Hello!

`, document.body); * ``` * - * @param value Any renderable value, typically a {@linkcode TemplateResult} - * created by evaluating a template tag like {@linkcode html} or - * {@linkcode svg}. + * @param value Any [renderable + * value](https://lit.dev/docs/templates/expressions/#child-expressions), + * typically a {@linkcode TemplateResult} created by evaluating a template tag + * like {@linkcode html} or {@linkcode svg}. * @param container A DOM container to render to. The first render will append * the rendered value to the container, and subsequent renders will * efficiently update the rendered value if the same result type was * previously rendered there. * @param options See {@linkcode RenderOptions} for options documentation. + * @see + * {@link https://lit.dev/docs/libraries/standalone-templates/#rendering-lit-html-templates| Rendering Lit HTML Templates} */ export const render = ( value: unknown, From 2717a5fca48f82f1f2fe2b8c795f7308c8ab443f Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Wed, 8 Jun 2022 11:01:40 -0700 Subject: [PATCH 5/6] Code review feedback: add back variable into example. I think it's helpful. --- packages/lit-html/src/lit-html.ts | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/lit-html/src/lit-html.ts b/packages/lit-html/src/lit-html.ts index a721495d98..44f6ac65ae 100644 --- a/packages/lit-html/src/lit-html.ts +++ b/packages/lit-html/src/lit-html.ts @@ -620,13 +620,14 @@ export interface RenderOptions { /** * Renders a value, usually a lit-html TemplateResult, to the container. * - * For example, to render and create the DOM for the TemplateResult describing - * "

Hello!

" to the container `document.body`: + * For example, to render "Hello, Zoe!" to the container `document.body` where + * the name "Zoe" is from a variable: * * ```js * import {html, render} from 'lit'; * - * render(html`

Hello!

`, document.body); + * const name = "Zoe"; + * render(html`

Hello, ${name}!

`, document.body); * ``` * * @param value Any [renderable From 15de7420cda971fa602c8654d7759450665c471c Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Fri, 10 Jun 2022 07:36:25 -0700 Subject: [PATCH 6/6] Code review feedback --- packages/lit-html/src/lit-html.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/lit-html/src/lit-html.ts b/packages/lit-html/src/lit-html.ts index 44f6ac65ae..4e16fcc835 100644 --- a/packages/lit-html/src/lit-html.ts +++ b/packages/lit-html/src/lit-html.ts @@ -620,8 +620,8 @@ export interface RenderOptions { /** * Renders a value, usually a lit-html TemplateResult, to the container. * - * For example, to render "Hello, Zoe!" to the container `document.body` where - * the name "Zoe" is from a variable: + * This example renders the text "Hello, Zoe!" inside a paragraph tag, appending + * it to the container `document.body`. * * ```js * import {html, render} from 'lit';