Skip to content

Commit cd61828

Browse files
committed
Add adding-props.md
1 parent ec6f4e8 commit cd61828

File tree

3 files changed

+67
-16
lines changed

3 files changed

+67
-16
lines changed

docs/.vitepress/config.ts

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ export default defineConfigWithTheme({
4242
{
4343
text: 'Iterators',
4444
link: '/guide/iterators.html'
45+
}, {
46+
text: 'Adding props',
47+
link: '/guide/adding-props.html'
4548
}
4649
]
4750
}, {

docs/api.md

Lines changed: 11 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,12 @@ Eligible VNodes will be passed to the provided callback. The callback should ret
2222

2323
A new array of VNodes is returned.
2424

25-
### Examples
25+
### See also
2626

27-
* [Adding a class](/examples.html#adding-a-class)
28-
* [Adding component v-model](/examples.html#adding-component-v-model)
29-
* [Adding a `ref` to a slot](/examples.html#adding-a-ref-to-a-slot)
27+
* [Example - Adding a class](/examples.html#adding-a-class)
28+
* [Example - Adding component v-model](/examples.html#adding-component-v-model)
29+
* [Example - Adding a `ref` to a slot](/examples.html#adding-a-ref-to-a-slot)
30+
* [Guide - Adding props](/guide/adding-props.html)
3031

3132
## betweenChildren()
3233

@@ -54,9 +55,9 @@ The exact position of the newly inserted nodes within the tree is an implementat
5455

5556
A new array will be returned and the passed array and its contents should be left unmodified. Any fragment nodes will be cloned as required to avoid mutating the input nodes. The returned array may contain some of the same nodes as the input array, as nodes are not cloned in cases where it can be avoided.
5657

57-
### Examples
58+
### See also
5859

59-
* [Inserting between children](/examples.html#inserting-between-children)
60+
* [Example - Inserting between children](/examples.html#inserting-between-children)
6061

6162
## eachChild()
6263

@@ -124,13 +125,10 @@ As with the other helpers, the children of fragments will be considered top-leve
124125

125126
The intended use case is for components that only support a single child node in a slot, like Vue's built-in components `<Transition>` and `<KeepAlive>`.
126127

127-
### Examples
128-
129-
* [Adding a `ref` to a slot](/examples.html#adding-a-ref-to-a-slot)
130-
131128
### See also
132129

133130
* [`findChild()`](#findchild)
131+
* [Example - Adding a `ref` to a slot](/examples.html#adding-a-ref-to-a-slot)
134132

135133
## findChild()
136134

@@ -250,13 +248,10 @@ Component nodes are treated as non-empty, but in practice a child component migh
250248

251249
This helper is written using `someChild()`. If the exact criteria it uses to decide emptiness are not correct for your use case then it can be used as an example and adapted accordingly.
252250

253-
### Examples
254-
255-
* [Checking for empty content](/examples.html#checking-for-empty-content)
256-
257251
### See also
258252

259253
* [`someChild()`](#somechild)
254+
* [Example - Checking for empty content](/examples.html#checking-for-empty-content)
260255

261256
## isFragment()
262257

@@ -374,9 +369,9 @@ If the callback returns `null` or `undefined`, the current node will be left in
374369

375370
A new array will be returned and the passed array and its contents should be left unmodified. Any fragment nodes will be cloned as required to avoid mutating the input nodes. The returned array may contain some of the same nodes of the input array, as nodes are not cloned in cases where it can be avoided.
376371

377-
### Examples
372+
### See also
378373

379-
* [Wrap children](/examples.html#wrap-children)
374+
* [Example - Wrap children](/examples.html#wrap-children)
380375

381376
## someChild()
382377

docs/guide/adding-props.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Adding props
2+
3+
VNode props can be used for a variety of purposes:
4+
5+
* Passing component props.
6+
* Passing component event listeners.
7+
* Setting HTML element attributes.
8+
* Setting HTML element properties.
9+
* Adding HTML element event listeners.
10+
11+
There are also the special props `ref` and `key`.
12+
13+
Calling a slot function will yield an array of VNodes. If we wish to add extra VNode props to the 'top-level' VNodes then we can use `addProps`.
14+
15+
This example will add the CSS class `my-child` to each of the VNodes:
16+
17+
```js
18+
import { addProps } from '@skirtle/vue-vnode-utils'
19+
20+
// Inside a render function
21+
const children = slots.default?.() ?? []
22+
23+
const newChildren = addProps(children, (vnode) => {
24+
return {
25+
class: 'my-child'
26+
}
27+
})
28+
```
29+
30+
See it on the SFC Playground: [Composition API](https://sfc.vuejs.org/#eNp1VMuO2zAM/BXCPcQB/EqLXtw8ut1zi556qYvCiZVEu7YkSLI3QZB/70ix89omyIEaDociKfoQPCmVdC0L8mBqVporS4bZVs0LwRsltaUDabaOaCUb1VpW0ZHWWjY0QtDoTHre8rp6BkUKJmzPSNJb2OVBSCFWUhgLxRbUmZMPP40HlFvWGKBDvjAc02xO30u7TZpyF2ZRb3MReoWkK+uWRTTJxmOoTNNTGSgAB4ipurQMJ6IpF5CkLm5kxepZEfj4IiC7VwxH0TZLpnGGNo6Zs8odrAnMk8JtQR4DWvFu/o2tpWbT1NkXGMkAO23i+Lvaein3OxxI0PHY0+9C509ry/QFnd51E+A0PdcXRMFpFHFTquTFSIGJHlxc0TuQOCePOAyjcOci2FqrTJ6mZr1y83kxidSbFFai0RzesISZJl5q+WaYhnARRIPGV/PKta2ZY8edQFPj1vLaJ7oIt0K9bhKMM33ER4nG3oM3aSvW3aYGOYWjYzrWTFRMu7k9LueO+q4kJ4sxHNHF90/2shrXS7H9/yIcqKyqn1oqc/Y/KtuvAtv5sIqty7ZGuLuJX8DwbwQxU0sLpfEwOA2XFnTaiR4j7IrbHMf99QPybn18IPrmZRcJAhYL+v3HpbyOWblq0RZEDPcOLzrRfaLzBa4QSNWlMTmNmn3s9VDY4OrfNgys5mD3GttwhLc9wqelvwQonupH3E/kfqGN3ddum5Mh2ekqS6kx2ZwmakdG1ryiD1mWfXGuptQbLmIrVU6f1a7HdvEbr+w2p49Z1oMKHeBiM7BOqX264PgP0vu57A==) | [Options API](https://sfc.vuejs.org/#eNp1VMmO2zAM/RXCLZAEiJe06MV1kk7n3KKnXuoenFiJNWMtkGSPg8D/PpS8ZZkEOYiP5HsiRfrsPUkZ1BXxYi/Re0Wl2aScMimUgeeClvmzQIMTbuCgBINZEF7DNnmW8pSTxiXl5JBVpYFzygH2Q5SOOwBuSC3WLm06QJ6ZbL4Y4hQxleKDZakqbmL42tntZaJVqQzJRw1qCNMT1Uj2KzNFwLJmHi37M+VzU1AdOPYlrKLF4lIg5fhPwrExaCC1LDND0AJIKEdlqH0mclKuU8/xpB6YkyRo8ortiEIbhdCM7Clr8LTCY8dw3Q+HIZrTevOTHIQiSWjPE4xiCFtuoPi3lfZU9nc+A4fWXR7Db1I3TwdD1IQmN0+JYBKO9XlLr5sDn2UyeNGC44y4jqa9A4XHlqcezoG1U68wRuo4DPVhb4fjRQdCHUM8BQqbQxkJiGb+Tok3TRQSpx6+Y8fxQ79SZUpio/2aY1P9ytDSCU3EFZevR3wyFj6KxxK1uQWvZHNSX0tjcIiOmihfEZ4TZd/tcTk3oXclDeODXbzfl4+W7QwFtP2OdSs1OrI8/6OE1KP/UdkP97C75rQRe8G1AV0K8/c3ZmtYg1uDzxbS2ByXuw0wY7uFf//7Jl3k7m1RSIuZw/XmE98SMHO9uVvA0UaaMtP4VZixk++48O6dox/eFhfx6ktQzGc4uLPlKO029aMV1eZU2v0MBu5OdycUNiGGlWxAi5Lm8CmKou/WxTJ1pNw3QsbwTTY91vhvNDdFDF+iqAclFkv5cYjqpJ2c174DBlzG3w==)
31+
32+
`addProps()` behaves much like the iterator functions discussed previously, skipping over fragments and walking their children instead. Text nodes and comment nodes are also skipped by default as they don't have props. The callback will be invoked for nodes corresponding to elements or components, with the node being passed to the callback as the first argument. In the example above the VNode isn't used by the callback, it just returns an object containing the props to add.
33+
34+
`vue-vnode-utils` will use [`cloneVNode()`](https://vuejs.org/api/render-function.html#clonevnode) to take copies of any VNodes that are modified, leaving the original tree unchanged.
35+
36+
VNodes represent event listeners using props that begin with `on`, followed by the event name in PascalCase. So, for example, a listener for the event `update:modelValue` can be added using the prop `onUpdate:modelValue`.
37+
38+
```js
39+
import { addProps } from '@skirtle/vue-vnode-utils'
40+
41+
// Inside a render function
42+
const children = slots.default?.() || []
43+
44+
const newChildren = addProps(children, (vnode) => {
45+
return {
46+
'onUpdate:modelValue'(newValue) {
47+
console.log(`update: ${newValue}`)
48+
}
49+
}
50+
})
51+
```
52+
53+
Added props will be merged using [`mergeProps()`](https://vuejs.org/api/render-function.html#mergeprops), with special handling for event listeners, `class` and `style`. Likewise, if the props include a `ref` property it will be added to any existing `ref`, rather than replacing it.

0 commit comments

Comments
 (0)