Skip to content

Commit 15f3d59

Browse files
skirtles-codeskirtles-code
committed
Add api.md
1 parent 4ef2ab9 commit 15f3d59

File tree

2 files changed

+392
-0
lines changed

2 files changed

+392
-0
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: 'Examples',
4444
link: '/examples.html'
45+
}, {
46+
text: 'API',
47+
link: '/api.html'
4548
}
4649
]
4750
}

‎docs/api.md

Lines changed: 389 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,389 @@
1+
# API
2+
3+
## addProps()
4+
5+
### Type
6+
7+
```ts
8+
function addProps(
9+
children: VNodeArrayChildren,
10+
callback: (vnode: VNode) => (Record<string, any> | null | void),
11+
options: IterationOptions = COMPONENTS_AND_ELEMENTS
12+
): VNodeArrayChildren
13+
```
14+
15+
### Description
16+
17+
Adds props to 'top-level' element and component VNodes in the passed array. Nodes directly in the array will be updated, as will the children of any fragment nodes in the array. Aside from fragment nodes, nested children will be skipped.
18+
19+
The [`options`](#iterationoptions) object can be set to `{ component: true }` or `{ element: true }` to limit iteration to just components or elements respectively.
20+
21+
Eligible VNodes will be passed to the provided callback. The callback should return an object containing props that need to be added to the VNode. The VNode itself will not be changed, it will be cloned using Vue's built-in `cloneVNode` helper.
22+
23+
A new array of VNodes is returned.
24+
25+
### Examples
26+
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)
30+
31+
## betweenChildren()
32+
33+
### Type
34+
35+
```ts
36+
function betweenChildren(
37+
children: VNodeArrayChildren,
38+
callback: (previousVNode: VNode, nextVNode: VNode) => (VNode | VNodeArrayChildren | string | number | void),
39+
options: IterationOptions = SKIP_COMMENTS
40+
): VNodeArrayChildren
41+
```
42+
43+
### Description
44+
45+
Inserts VNodes between adjacent 'top-level' siblings. The children of fragments will be considered 'top-level' nodes, and the children of different fragments will still be treated as adjacent siblings if there are no other eligible nodes between them.
46+
47+
The [`options`](#iterationoptions) object can be used to decide which node types should be passed to the callback. If no options object is passed then comment nodes will be skipped. If an `options` object is passed, all nodes will be skipped by default unless explicitly ruled in.
48+
49+
Each invocation of the callback will be passed two nodes, the `previousNode` and the `nextNode`. The `nextNode` for the current invocation of the callback will become the `previousNode` on the next invocation. If any of the children are not fully instantiated VNodes, such as strings of text, they will be converted to full VNodes prior to being passed to the callback.
50+
51+
If the callback returns `null` or `undefined` (or an empty array) then no change is made to the tree. If a single VNode is returned it will be inserted into the tree between the `previousNode` and `nextNode`. If an array of nodes is returned then they will all be inserted between the current two nodes.
52+
53+
The exact position of the newly inserted nodes within the tree is an implementation detail and should not be relied upon. The current pair of nodes might be in different fragments, or they might already have other nodes between them that are being skipped by the `options`. No guarantees are made about the positions of the inserted nodes relative to other nodes, only that they will be somewhere between the pair passed to the callback.
54+
55+
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.
56+
57+
### Examples
58+
59+
* [Inserting between children](/examples.html#inserting-between-children)
60+
61+
## eachChild()
62+
63+
### Type
64+
65+
```ts
66+
function eachChild(
67+
children: VNodeArrayChildren,
68+
callback: (vnode: VNode) => void,
69+
options: IterationOptions = ALL_VNODES
70+
): void
71+
```
72+
73+
### Description
74+
75+
An iterator for 'top-level' nodes, comparable to `Array.protoype.forEach`. The children of a fragment will be considered 'top-level' nodes rather than the fragment itself.
76+
77+
The callback will be passed fully instantiated VNodes. Children will be converted to VNodes as required.
78+
79+
The [`options`](#iterationoptions) object can be used to decide which node types should be passed to the callback. If no options object is passed then all nodes will be iterated. If an `options` object is passed, all nodes will be skipped by default unless explicitly ruled in.
80+
81+
## everyChild()
82+
83+
### Type
84+
85+
```ts
86+
function everyChild(
87+
children: VNodeArrayChildren,
88+
callback: (vnode: VNode) => unknown,
89+
options: IterationOptions = ALL_VNODES
90+
): boolean
91+
```
92+
93+
### Description
94+
95+
An iterator for 'top-level' nodes, comparable to `Array.protoype.every`. The children of a fragment will be considered 'top-level' nodes rather than the fragment itself.
96+
97+
If the callback returns a falsy value then the iteration will exit and `everyChild()` will return `false`. Otherwise `everyChild()` will return `true` once all nodes have been iterated.
98+
99+
The callback will be passed fully instantiated VNodes. Children will be converted to VNodes as required.
100+
101+
The [`options`](#iterationoptions) object can be used to decide which node types should be passed to the callback. If no options object is passed then all nodes will be iterated. If an `options` object is passed, all nodes will be skipped by default unless explicitly ruled in.
102+
103+
## extractSingleChild()
104+
105+
### Type
106+
107+
```ts
108+
function extractSingleChild(children: VNodeArrayChildren): VNode | undefined
109+
```
110+
111+
### Description
112+
113+
Pulls out a single 'top-level' child VNode from an array of children. The extracted node must be either an element or a component VNode. If other non-empty children are found then a warning will be logged in development builds.
114+
115+
As with the other helpers, the children of fragments will be considered top-level children.
116+
117+
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>`.
118+
119+
### Examples
120+
121+
* [Adding a `ref` to a slot](/examples.html#adding-a-ref-to-a-slot)
122+
123+
### See also
124+
125+
* [`findChild()`](#findchild)
126+
127+
## findChild()
128+
129+
### Type
130+
131+
```ts
132+
function findChild(
133+
children: VNodeArrayChildren,
134+
callback: (vnode: VNode) => unknown,
135+
options: IterationOptions = ALL_VNODES
136+
): (VNode | undefined)
137+
```
138+
139+
### Description
140+
141+
An iterator for 'top-level' nodes, comparable to `Array.protoype.find`. The children of a fragment will be considered 'top-level' nodes rather than the fragment itself.
142+
143+
If the callback returns a truthy value then the iteration will exit and `findChild()` will return the current VNode. Otherwise `findChild()` will return `undefined` once all nodes have been iterated.
144+
145+
The callback will be passed fully instantiated VNodes. Children will be converted to VNodes as required. As a result, it is possible that the returned VNode is not actually present in the original array of nodes. In practice this should rarely be a problem, as slot functions return fully instantiated VNodes.
146+
147+
The [`options`](#iterationoptions) object can be used to decide which node types should be passed to the callback. If no options object is passed then all nodes will be iterated. If an `options` object is passed, all nodes will be skipped by default unless explicitly ruled in.
148+
149+
## getText()
150+
151+
### Type
152+
153+
```ts
154+
function getText(vnode: VNode | string | number): string | undefined
155+
```
156+
157+
### Description
158+
159+
Returns the text content of a text node. If the passed value is not a text node (consistent with [`isText()`](#istext)) then `undefined` will be returned instead.
160+
161+
## getType()
162+
163+
### Type
164+
165+
```ts
166+
function getType(vnode: any):
167+
'comment' |
168+
'component' |
169+
'element' |
170+
'fragment' |
171+
'static' |
172+
'text' |
173+
undefined
174+
```
175+
176+
### Description
177+
178+
Returns a string describing the type of VNode passed. The passed node doesn't have to be a fully instantiated VNode, it supports a number of other values, consistent with `render` functions and the valid values for children of `h`.
179+
180+
If the passed value doesn't appear to be convertible to a VNode, the returned value will be `undefined`.
181+
182+
## isComment()
183+
184+
### Type
185+
186+
```ts
187+
function isComment(vnode: any): vnode is (null | undefined | boolean | (VNode & { type: Comment }))
188+
```
189+
190+
### Description
191+
192+
Returns `true` if the passed value is considered to be a comment. This could be a comment VNode, or `undefined`, `null`, `false`, or `true`. This is consistent with how `render` functions and `h` treat children, with all of those values being converted to comment nodes.
193+
194+
## isComponent()
195+
196+
### Type
197+
198+
```ts
199+
function isComponent(vnode: any): vnode is (VNode & { type: Component })
200+
```
201+
202+
### Description
203+
204+
Returns `true` if the passed value is a component VNode. This includes both stateful and functional components.
205+
206+
### See also
207+
208+
* [`isFunctionalComponent()`](#isfunctionalcomponent)
209+
* [`isStatefulComponent()`](#isstatefulcomponent)
210+
211+
## isElement()
212+
213+
### Type
214+
215+
```ts
216+
function isElement(vnode: any): vnode is (VNode & { type: string })
217+
```
218+
219+
### Description
220+
221+
Returns `true` if the passed value is an element VNode, e.g. a `<div>` or `<span>`.
222+
223+
## isEmpty()
224+
225+
### Type
226+
227+
```ts
228+
function isEmpty(children: VNodeArrayChildren): boolean
229+
```
230+
231+
### Description
232+
233+
A helper to check whether an array of VNodes is empty. Comment nodes and collapsible white-space are considered empty content. Fragment VNodes are treated as empty if all their children are considered empty.
234+
235+
CSS is not taken into account, so the resulting DOM nodes may not be visible. Content hidden with `v-show`, for example, will not be considered empty.
236+
237+
Component nodes are treated as non-empty, but in practice a child component might not render anything. `isEmpty()` is intended to be used during rendering, and child components aren't rendered until after their parent component. `isEmpty()` can only make a best guess, but a completely accurate check would need to be based on the DOM post-rendering.
238+
239+
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.
240+
241+
### Examples
242+
243+
* [Checking for empty content](/examples.html#checking-for-empty-content)
244+
245+
### See also
246+
247+
* [`someChild()`](#somechild)
248+
249+
## isFragment()
250+
251+
### Type
252+
253+
```ts
254+
function isFragment(vnode: any): vnode is ((VNode & { type: typeof Fragment }) | VNodeArrayChildren)
255+
```
256+
257+
### Description
258+
259+
Returns `true` if the passed value is considered a fragment. This could either be a fragment VNode or an array. This is consistent with how `render` functions and `h` treat children, with arrays being converted to fragments.
260+
261+
## isFunctionalComponent()
262+
263+
### Type
264+
265+
```ts
266+
function isFunctionalComponent(vnode: any): vnode is (VNode & { type: FunctionalComponent })
267+
```
268+
269+
### Description
270+
271+
Returns `true` if the passed value is a VNode for a [functional component](https://vuejs.org/guide/extras/render-function.html#functional-components).
272+
273+
### See also
274+
275+
* [`isComponent()`](#iscomponent)
276+
* [`isStatefulComponent()`](#isstatefulcomponent)
277+
278+
## isStatefulComponent()
279+
280+
### Type
281+
282+
```ts
283+
function isStatefulComponent(vnode: any): vnode is (VNode & { type: ComponentOptions })
284+
```
285+
286+
### Description
287+
288+
Returns `true` if the passed value is a VNode for a stateful (i.e. non-functional) component. This includes async components
289+
290+
### See also
291+
292+
### See also
293+
294+
* [`isComponent()`](#iscomponent)
295+
* [`isFunctionalComponent()`](#isfunctionalcomponent)
296+
297+
## isStatic()
298+
299+
### Type
300+
301+
```ts
302+
function isStatic(vnode: any): vnode is (VNode & { type: typeof Static })
303+
```
304+
305+
### Description
306+
307+
Returns `true` if the passed value is a static VNode. Static VNodes are a special kind of VNode used to render large quantities of static HTML without incurring the cost of creating an individual VNode for each element. They aren't returned from slot functions, so in practice they're unlikely to be encountered in the normal use cases for `vue-vnode-utils`.
308+
309+
## isText()
310+
311+
### Type
312+
313+
```ts
314+
function isText(vnode: any): vnode is (string | number | (VNode & { type: Text }))
315+
```
316+
317+
### Description
318+
319+
Returns `true` if the passed value is considered to be text. This could be a text VNode, or a string, or a number. This is consistent with how `render` functions and `h` treat children, with strings and numbers being converted to text nodes.
320+
321+
## IterationOptions
322+
323+
### Type
324+
325+
```ts
326+
type IterationOptions = {
327+
component?: boolean
328+
comment?: boolean
329+
element?: boolean
330+
static?: boolean
331+
text?: boolean
332+
}
333+
```
334+
335+
### Description
336+
337+
Options that can be passed to the iterators to filter the node types that should be passed to the callback.
338+
339+
Some common configurations are available via the constants `ALL_VNODES`, `COMPONENTS_AND_ELEMENTS` and `SKIP_COMMENTS`.
340+
341+
## replaceChildren()
342+
343+
### Type
344+
345+
```ts
346+
function replaceChildren(
347+
children: VNodeArrayChildren,
348+
callback: (vnode: VNode) => (VNode | VNodeArrayChildren | string | number | void),
349+
options: IterationOptions = SKIP_COMMENTS
350+
): VNodeArrayChildren
351+
```
352+
353+
### Description
354+
355+
Adds, removes or replaces 'top-level' VNodes in the passed array. Eligible nodes directly in the array will be passed to the callback, as will the children of any fragment nodes in the array. Aside from fragment nodes, nested children will be skipped.
356+
357+
The [`options`](#iterationoptions) object can be used to decide which node types should be passed to the callback. If no options object is passed then comment nodes will be skipped. If an `options` object is passed, all nodes will be skipped by default unless explicitly ruled in.
358+
359+
The callback will be passed the VNodes in tree order. If any of the children are not fully instantiated VNodes, such as strings of text, they will be converted to full VNodes prior to being passed to the callback. Nodes that aren't passed to the callback will retain their positions within the VNode tree.
360+
361+
If the callback returns `null` or `undefined`, the current node will be left in its current position in the VNode tree. If the callback returns a single VNode, it will replace the original VNode in the tree. If the callback returns an array, all the VNodes in the array will be used to replace the current node. The current VNode can be included in the returned array, allowing for nodes to be added around the current node. An empty array can be used to remove the current VNode.
362+
363+
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.
364+
365+
### Examples
366+
367+
* [Wrap children](/examples.html#wrap-children)
368+
369+
## someChild()
370+
371+
### Type
372+
373+
```ts
374+
function someChild(
375+
children: VNodeArrayChildren,
376+
callback: (vnode: VNode) => unknown,
377+
options: IterationOptions = ALL_VNODES
378+
): boolean
379+
```
380+
381+
### Description
382+
383+
An iterator for 'top-level' nodes, comparable to `Array.protoype.some`. The children of a fragment will be considered 'top-level' nodes rather than the fragment itself.
384+
385+
If the callback returns a truthy value then the iteration will exit and `someChild()` will return `true`. Otherwise `someChild()` will return `false` once all nodes have been iterated.
386+
387+
The callback will be passed fully instantiated VNodes. Children will be converted to VNodes as required.
388+
389+
The [`options`](#iterationoptions) object can be used to decide which node types should be passed to the callback. If no options object is passed then all nodes will be iterated. If an `options` object is passed, all nodes will be skipped by default unless explicitly ruled in.

0 commit comments

Comments
 (0)