0
# DOM Selection
1

2
Core CSS selector-based element selection functionality providing comprehensive querying capabilities with high performance through compiled resolvers and memoization.
3

4
## Capabilities
5

6
### Select Function
7

8
Returns an array of all elements matching the specified CSS selector within the given context.
9

10
```javascript { .api }
11
/**
12
 * Returns array of all elements matching selector
13
 * @param selector - CSS selector string
14
 * @param context - Search context element (defaults to document)
15
 * @param callback - Optional callback invoked for each match
16
 * @returns Array of matching elements
17
 */
18
function select(selector, context, callback);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const nwsapi = require("nwsapi");
25

26
// Basic selection
27
const paragraphs = nwsapi.select('p', document);
28

29
// With context
30
const links = nwsapi.select('a', document.getElementById('nav'));
31

32
// Complex selectors
33
const elements = nwsapi.select('div.container > p:first-child', document);
34

35
// With callback
36
nwsapi.select('.highlight', document, function(element) {
37
  console.log('Found highlighted element:', element);
38
});
39

40
// Advanced CSS4 selectors
41
const matches = nwsapi.select(':has(> img)', document);
42
const scopedElements = nwsapi.select(':scope > div', container);
43
```
44

45
### Match Function
46

47
Tests whether an element matches the specified CSS selector.
48

49
```javascript { .api }
50
/**
51
 * Tests if element matches selector
52
 * @param selector - CSS selector string
53
 * @param element - Element to test
54
 * @param callback - Optional callback invoked for matched element
55
 * @returns Boolean indicating match
56
 */
57
function match(selector, element, callback);
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
const nwsapi = require("nwsapi");
64

65
// Basic matching
66
const isButton = nwsapi.match('button', element);
67
const hasClass = nwsapi.match('.active', element);
68

69
// Complex matching
70
const isFirstChild = nwsapi.match(':first-child', element);
71
const matchesComplex = nwsapi.match('div.container > p:nth-child(2n+1)', element);
72

73
// With callback
74
const matched = nwsapi.match('.important', element, function(el) {
75
  console.log('Element matches important class');
76
});
77
```
78

79
### First Function
80

81
Returns the first element matching the specified CSS selector within the given context.
82

83
```javascript { .api }
84
/**
85
 * Returns first element matching selector
86
 * @param selector - CSS selector string
87
 * @param context - Search context element (defaults to document)
88
 * @param callback - Optional callback invoked for matched element
89
 * @returns First matching element or null
90
 */
91
function first(selector, context, callback);
92
```
93

94
**Usage Examples:**
95

96
```javascript
97
const nwsapi = require("nwsapi");
98

99
// Find first match
100
const firstParagraph = nwsapi.first('p', document);
101
const firstButton = nwsapi.first('button.primary', document);
102

103
// With context
104
const firstLink = nwsapi.first('a', navigation);
105

106
// Complex selectors
107
const firstChild = nwsapi.first('div:first-child', container);
108
const firstOfType = nwsapi.first('h1:first-of-type', document);
109
```
110

111
### Closest Function
112

113
Returns the nearest ancestor element (including the element itself) that matches the specified CSS selector.
114

115
```javascript { .api }
116
/**
117
 * Returns nearest ancestor matching selector
118
 * @param selector - CSS selector string
119
 * @param context - Starting element
120
 * @param callback - Optional callback invoked for matched element
121
 * @returns Nearest matching ancestor or null
122
 */
123
function closest(selector, context, callback);
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
const nwsapi = require("nwsapi");
130

131
// Find closest ancestor
132
const form = nwsapi.closest('form', inputElement);
133
const container = nwsapi.closest('.container', element);
134

135
// Navigate up DOM tree
136
const listItem = nwsapi.closest('li', element);
137
const section = nwsapi.closest('section, article', element);
138

139
// With callback
140
const parent = nwsapi.closest('[data-component]', element, function(ancestor) {
141
  console.log('Found component ancestor:', ancestor.dataset.component);
142
});
143
```
144

145
## Supported Selectors
146

147
NWSAPI supports a comprehensive range of CSS selectors including:
148

149
### Basic Selectors
150
- **Type selectors**: `div`, `p`, `span`
151
- **Class selectors**: `.class-name`
152
- **ID selectors**: `#element-id`
153
- **Universal selector**: `*`
154
- **Attribute selectors**: `[attr]`, `[attr="value"]`, `[attr~="value"]`, `[attr|="value"]`, `[attr^="value"]`, `[attr$="value"]`, `[attr*="value"]`
155

156
### Combinators
157
- **Descendant**: `A B`
158
- **Child**: `A > B`
159
- **Adjacent sibling**: `A + B`
160
- **General sibling**: `A ~ B`
161

162
### Pseudo-classes
163
- **Structural**: `:first-child`, `:last-child`, `:nth-child()`, `:nth-of-type()`, `:only-child`, `:empty`, `:root`
164
- **Logical**: `:not()`, `:is()`, `:where()`, `:has()`
165
- **Link**: `:link`, `:visited`, `:any-link`
166
- **User action**: `:hover`, `:active`, `:focus`, `:focus-within`, `:focus-visible`
167
- **Input**: `:enabled`, `:disabled`, `:checked`, `:indeterminate`, `:required`, `:optional`, `:valid`, `:invalid`
168
- **Language**: `:lang()`
169
- **Location**: `:target`, `:scope`
170

171
### Pseudo-elements
172
- `::before`, `::after`, `::first-line`, `::first-letter`, `::selection`
173

174
## Performance Notes
175

176
- **Memoization**: Compiled selectors are cached for reuse, providing superior performance on repeated queries
177
- **Right-to-left parsing**: Optimized parsing strategy that matches browser behavior
178
- **Context optimization**: Queries are optimized based on the provided context
179
- **Lazy compilation**: Selectors are compiled only when first used