0
# Children Utilities
1

2
Comprehensive utilities for working with component children, providing safe iteration and manipulation methods.
3

4
## Capabilities
5

6
### Children Object
7

8
Collection of utilities for safely working with component children.
9

10
```javascript { .api }
11
/**
12
 * Children utilities for safe child manipulation
13
 */
14
const Children = {
15
  /**
16
   * Maps over children with proper context handling
17
   * @param {ComponentChildren} children - Component children to map
18
   * @param {function} fn - Mapping function (child, index) => newChild
19
   * @param {any} ctx - Optional context for the mapping function
20
   * @returns {Array} Array of mapped children
21
   */
22
  map(children, fn, ctx);
23
  
24
  /**
25
   * Iterates over children without returning values
26
   * @param {ComponentChildren} children - Component children to iterate
27
   * @param {function} fn - Iteration function (child, index) => void
28
   * @param {any} ctx - Optional context for the iteration function
29
   */
30
  forEach(children, fn, ctx);
31
  
32
  /**
33
   * Counts the number of children
34
   * @param {ComponentChildren} children - Children to count
35
   * @returns {number} Number of children
36
   */
37
  count(children);
38
  
39
  /**
40
   * Ensures exactly one child is present
41
   * @param {ComponentChildren} children - Children to validate
42
   * @returns {VNode} The single child
43
   * @throws {Error} If zero or multiple children
44
   */
45
  only(children);
46
  
47
  /**
48
   * Converts children to a flat array
49
   * @param {ComponentChildren} children - Children to convert
50
   * @returns {Array} Flat array of children
51
   */
52
  toArray(children);
53
};
54
```
55

56
**Usage Examples:**
57

58
```javascript
59
import { Children } from 'preact-compat';
60

61
function ParentComponent({ children }) {
62
  // Map over children to add props
63
  const mappedChildren = Children.map(children, (child, index) => {
64
    return cloneElement(child, { key: index, parentIndex: index });
65
  });
66
  
67
  // Count children
68
  const childCount = Children.count(children);
69
  
70
  // Ensure single child
71
  const singleChild = Children.only(children); // Throws if not exactly one
72
  
73
  // Convert to array for manipulation
74
  const childArray = Children.toArray(children);
75
  
76
  return (
77
    <div>
78
      <p>Child count: {childCount}</p>
79
      {mappedChildren}
80
    </div>
81
  );
82
}
83

84
// Usage
85
function App() {
86
  return (
87
    <ParentComponent>
88
      <div>Child 1</div>
89
      <div>Child 2</div>
90
      <div>Child 3</div>
91
    </ParentComponent>
92
  );
93
}
94
```
95

96
### Advanced Children Patterns
97

98
```javascript
99
import { Children, cloneElement } from 'preact-compat';
100

101
// Add common props to all children
102
function withCommonProps(children, commonProps) {
103
  return Children.map(children, child => {
104
    if (isValidElement(child)) {
105
      return cloneElement(child, commonProps);
106
    }
107
    return child;
108
  });
109
}
110

111
// Filter children by type
112
function filterChildrenByType(children, targetType) {
113
  return Children.toArray(children).filter(child => 
114
    isValidElement(child) && child.type === targetType
115
  );
116
}
117

118
// Recursive children processing
119
function processChildrenRecursively(children, processor) {
120
  return Children.map(children, child => {
121
    if (isValidElement(child) && child.props.children) {
122
      return cloneElement(child, {
123
        children: processChildrenRecursively(child.props.children, processor)
124
      });
125
    }
126
    return processor(child);
127
  });
128
}
129
```
130

131
## Types
132

133
```javascript { .api }
134
type ComponentChildren = VNode<any> | object | string | number | boolean | null | undefined | Array<ComponentChildren>;
135

136
interface ChildrenAPI {
137
  map<T>(children: ComponentChildren, fn: (child: any, index: number) => T, ctx?: any): T[];
138
  forEach(children: ComponentChildren, fn: (child: any, index: number) => void, ctx?: any): void;
139
  count(children: ComponentChildren): number;
140
  only(children: ComponentChildren): VNode;
141
  toArray(children: ComponentChildren): Array<any>;
142
}
143
```