Additional documentation for html and nothing
#2162
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
📊 Tachometer Benchmark ResultsSummarynop-update
render
update
update-reflect
Resultslit-element-list
render
update
update-reflect
lit-html-kitchen-sink
render
update
nop-update
lit-html-repeat
render
update
lit-html-template-heavy
render
update
reactive-element-list
render
update
update-reflect
|
AndrewJakubowicz
force-pushed
the
expand-lit2-docs2
branch
from
2d4d0c1
to
049b1dc
Compare
aomarks
reviewed
Sep 16, 2021
packages/lit-html/src/lit-html.ts
Outdated
| * const header = (title: string) => html`<h1>${title}</h1>`; | ||
| * ``` | ||
| * | ||
| * The `html` tag takes the literal strings and embedded expression values for |
There was a problem hiding this comment.
Does this text come from lit.dev, or is it new?
It does seem like there's a downside to having too detailed documentation here. Otherwise we are maintaining the same documentation in two different places, which will definitely get out of sync.
I wonder if we should do something a little more concise, and then link to the relevant lit.dev section?
There was a problem hiding this comment.
Yeah, I don't think we need to describe how this works. I think we might hit a couple of points like:
- this returns a description of the DOM to render as a value
- Maybe that the value is a TemplateResult (but even that's pretty drilled in)
- It captures the expression values and the static template strings
- The result needs to be passed to render() to do anything
- If a template result comes from the same expression as a previously rendered result, it's updated instead of replaced
- Point to the template docs on lit.dev
There was a problem hiding this comment.
Agreed! Do we have this info on lit.dev (I couldn't find it). My reference was: https://lit-html.polymer-project.org/guide/writing-templates
Is the plan that lit.dev contains all the documentation for various packages?
There was a problem hiding this comment.
Yes, lit.dev is completely replacing the other sites.
There was a problem hiding this comment.
I opened issue: lit/lit.dev#504, since not sure if we have a lit.dev location for these concepts yet.
Made much more succinct in follow up commit. Thank you!
packages/lit-html/src/lit-html.ts
Outdated
| @@ -327,6 +336,19 @@ export const noChange = Symbol.for('lit-noChange'); | |||
|
|
|||
| /** | |||
| * A sentinel value that signals a ChildPart to fully clear its content. | |||
| * | |||
| * The values `undefined`, `null`, and the empty string `''` all render an empty | |||
There was a problem hiding this comment.
This changed in Lit 2. In child expressions, undefined, null, '', and nothing all render the same thing now - no nodes at all. In attribute expressions undefined, etc., will render an empty string and nothing will remove the attribute. In property expressions nothing becomes undefined.
There was a problem hiding this comment.
This is incredible info thank you. Will add.
justinfagnani
approved these changes
Sep 19, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Addresses github issue: #1883
Context
Documenting lit-html's
htmlandnothing. The API documentation is sparse so I've borrowed heavily from the original lit-html polymer website.Let me know if there is too much (especially in the
htmltag case) and if we only want to keep a smaller amount or something different. Intent was to share that there isn't string concatenation going on under the hood.Identified as currently on lit.dev there is minimal documentation and they are heavily used in Lit: https://lit.dev/docs/api/templates/
Testing
Tested with mouse over in VsCode.
Thank you!