Split <slot> into two features and add statuses #880
Conversation
| # Do not edit this file by hand. Edit the source file instead! | ||
|
|
||
| name: Imperative slot assignment | ||
| description: The `assign()` method for `<slot>` elements does TODO. Also known as manual slot assignment. |
There was a problem hiding this comment.
@mfreed7 can you help me describe what this feature is? https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assign doesn't really say. I know it's the imperative alternative to the declarative method, but how to describe what it's for in simple terms?
There was a problem hiding this comment.
Sure. I agree that the MDN description looks more or less like a copy of the spec. Not how a developer would understand it. Maybe this?
The assign() method of the HTMLSlotElement interface assigns the provided nodes to that slot, provided they are direct children of the shadow host. This allows the slotting behavior to be controlled via Javascript, rather than automatically by the browser based on matching up the slot and name attributes. For this reason, this feature is also known as "manual slot assignment".
In order for assign() to have any effect, the shadow root must have been created with the slotAssignment parameter set to "manual".
There was a problem hiding this comment.
Thank you @mfreed7, that is very very helpful! I think we'll need to shorten it somewhat to fit our (self-imposed) length limit on descriptions, but I'll try to retain all the information.
There was a problem hiding this comment.
Here's my updated wording:
| description: The `assign()` method for `<slot>` elements does TODO. Also known as manual slot assignment. | |
| description: The `assign()` method for `<slot>` elements assigns the given nodes to the slot. This allow you to control slotting using Javascript, as an alternative to using the `slot` and `name` HTML attributes. The nodes must be direct children of a shadow host and the shadow root must be created with the `slotAssignment `parameter set to "manual". Also known as manual slot assignment. |
Differences to @mfreed7's suggestion explained:
- Sticking with
<slot>element overHTMLSlotElementinterface to match existing descriptions (also written by me) but filed Guideline for HTML element APIs #900 - "Allows you" to follow https://github.com/web-platform-dx/web-features/blob/main/docs/README.md#allows
- Tried to combine the two rules about where the nodes are in the DOM and the requirement for
slotAssignmentinto a single sentence. - Aka at the end in the style of https://github.com/web-platform-dx/web-features/blob/main/docs/README.md#also-known-as
No description provided.