Adds docs about templating, minor housekeeping #180
Conversation
klebba
force-pushed
the
minor-housekeeping
branch
from
86ad434
to
b188fce
Compare
| return html` | ||
| <select name="my-options"> | ||
| ${repeat(options, option => option.id, option => html` | ||
| <option value="${option.value}" ?selected="${option.id === selectedId}"> |
There was a problem hiding this comment.
TODO: does this example work? #179 tracks a potential problem
There was a problem hiding this comment.
it works now — but we should use map
klebba
force-pushed
the
minor-housekeeping
branch
3 times, most recently
from
4b1b285
to
50454ab
Compare
klebba
force-pushed
the
minor-housekeeping
branch
from
e027639
to
a9acda7
Compare
doc/TEMPLATES.md
Outdated
| | attribute | `<div foo="${bar}">` | | ||
| | attribute (boolean) | `<div ?foo="${bar}">` | | ||
| | property | `<div .foo="${bar}">` | | ||
| | text | `<div>${foo}</div>` | |
There was a problem hiding this comment.
I wonder if we should just say content here? I like text / content? I find the additional line slightly confusing.
doc/TEMPLATES.md
Outdated
| | text | `<div>${foo}</div>` | | ||
| | content | `${foo}` | | ||
|
|
||
| Equivalent to: |
There was a problem hiding this comment.
nit: “Equivalent” might be too strong a word. Maybe “Compare with:” or something?
| - If the features of our custom element are really basic, we could do this easily without any libraries. As your features become more complex some common concerns and conveniences start to emerge (in our case these items became the `x-element` project). | ||
| - Regardless of the manner in which the element has been defined, the current page context now guarantees a relationship between the new tag `<my-custom-element>` and the class `MyCustomElement`. This concept is critical to understand because this normalization liberates developers from the need to choose a single framework (or framework version) to define their features. | ||
| - Note that it is possible to create a DOM node named `my-custom-element` _before_ the custom element has been defined via `customElements.define('my-custom-element', MyCustomElement)`. This can be done using declarative HTML like `<my-custom-element></my-custom-element>` or with imperative API calls like `const el = document.createElement('my-custom-element')`. However at this stage the `my-custom-element` DOM node is functionally equivalent to a `span`. | ||
| - When `my-custom-element` is eventually defined within the page context all instances of that element are instantly "upgraded" using the `MyCustomElement` class. This is the second important concept: DOM composition is independent from custom element definition. This decoupling enables composible feature developers to have flexibility when selecting a DOM template engine. Because child nodes within `my-custom-element` can be fully encapsulated using the [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) creating and managing them becomes an implementation detail that template engines have no awareness of. |
There was a problem hiding this comment.
I feel like some of the discussion in here is more about element lifecycle versus choosing a template engine. Might want to figure out if some of this makes sense elsewhere?
|
|
||
| * Custom elements are not a framework (native feature) | ||
| * Custom elements provide DOM, JS and CSS encapsulation (native feature) | ||
| * Developers can choose a framework to manage the DOM within their custom element |
There was a problem hiding this comment.
Just another thought on this — I think this file is trying to cover both picking a template engine and interoperability. IMO, these are kinda different topics. I kinda get why you’re trying to cover them both in here, but I also find it confusing because it conflates the two concepts.
There was a problem hiding this comment.
thats good feedback — shall we defer to a future revision?
doc/TESTING.md
Outdated
There was a problem hiding this comment.
The way I typically test locally is to npm start, then, visit the /test page in the browser. Can we cover that case in here as well?
| "tap-parser": "^15.3.1" | ||
| "eslint": "^9.8.0", | ||
| "puppeteer": "^23.0.2", | ||
| "tap-parser": "^18.0.0" |
There was a problem hiding this comment.
Hrm, they sorta bundled all the tapjs stuff into a single changelog. It’s much harder to tell exactly what changed related to the tap-parser library. Anyways, it should still be working with TAP 14 output, so that should still interop with x-test.
klebba
force-pushed
the
minor-housekeeping
branch
from
a9acda7
to
09f5ba7
Compare
Covers templating in more detail. Creates
docdirectory.