0
# DOM Configuration
1

2
Validation utilities for HTML, SVG, and MathML elements and attributes. These functions are used by Vue's compiler for proper DOM handling, SSR safety, and template validation.
3

4
## Capabilities
5

6
### Element Tag Validation
7

8
Functions for validating different types of DOM element tags.
9

10
```typescript { .api }
11
/**
12
 * Check if tag name is a valid HTML element
13
 * Compiler-only - do not use in runtime unless behind __DEV__ flag
14
 * @param key - Tag name to validate
15
 * @returns True if tag is a known HTML element
16
 */
17
function isHTMLTag(key: string): boolean;
18

19
/**
20
 * Check if tag name is a valid SVG element  
21
 * Compiler-only - do not use in runtime unless behind __DEV__ flag
22
 * @param key - Tag name to validate
23
 * @returns True if tag is a known SVG element
24
 */
25
function isSVGTag(key: string): boolean;
26

27
/**
28
 * Check if tag name is a valid MathML element
29
 * Compiler-only - do not use in runtime unless behind __DEV__ flag  
30
 * @param key - Tag name to validate
31
 * @returns True if tag is a known MathML element
32
 */
33
function isMathMLTag(key: string): boolean;
34

35
/**
36
 * Check if tag is a void (self-closing) element
37
 * Compiler-only - do not use in runtime unless behind __DEV__ flag
38
 * @param key - Tag name to validate  
39
 * @returns True if tag is void (area, br, img, input, etc.)
40
 */
41
function isVoidTag(key: string): boolean;
42
```
43

44
### Boolean Attribute Validation
45

46
Functions for identifying and handling boolean HTML attributes.
47

48
```typescript { .api }
49
/**
50
 * Check if attribute is a special boolean attribute
51
 * These have different property names than their DOM counterparts
52
 * @param key - Attribute name to check
53
 * @returns True if attribute is special boolean type
54
 */
55
function isSpecialBooleanAttr(key: string): boolean;
56

57
/**
58
 * Check if attribute is a boolean attribute (any type)
59
 * Includes both special and regular boolean attributes
60
 * @param key - Attribute name to check
61
 * @returns True if attribute is boolean type
62
 */
63
function isBooleanAttr(key: string): boolean;
64

65
/**
66
 * Check if boolean attribute value should be included in output
67
 * Boolean attributes are included if truthy or empty string
68
 * @param value - Attribute value to check
69
 * @returns True if attribute should be rendered
70
 */
71
function includeBooleanAttr(value: unknown): boolean;
72
```
73

74
### Attribute Name Validation
75

76
Functions for validating attribute names and ensuring SSR safety.
77

78
```typescript { .api }
79
/**
80
 * Check if attribute name is safe for server-side rendering
81
 * Validates against unsafe characters that could cause issues
82
 * @param name - Attribute name to validate
83
 * @returns True if attribute name is SSR-safe
84
 */
85
function isSSRSafeAttrName(name: string): boolean;
86

87
/**
88
 * Check if attribute is a known HTML attribute
89
 * Used for stringification of runtime static nodes
90
 * @param key - Attribute name to check  
91
 * @returns True if attribute is a known HTML attribute
92
 */
93
function isKnownHtmlAttr(key: string): boolean;
94

95
/**
96
 * Check if attribute is a known SVG attribute
97
 * @param key - Attribute name to check
98
 * @returns True if attribute is a known SVG attribute
99
 */
100
function isKnownSvgAttr(key: string): boolean;
101

102
/**
103
 * Check if attribute is a known MathML attribute  
104
 * @param key - Attribute name to check
105
 * @returns True if attribute is a known MathML attribute
106
 */
107
function isKnownMathMLAttr(key: string): boolean;
108
```
109

110
### Attribute Value Validation
111

112
Functions for validating attribute values for rendering.
113

114
```typescript { .api }
115
/**
116
 * Check if attribute value can be rendered
117
 * Only string, number, and boolean values are renderable
118
 * @param value - Attribute value to check
119
 * @returns True if value can be safely rendered as attribute
120
 */
121
function isRenderableAttrValue(value: unknown): boolean;
122
```
123

124
### Property Name Mapping
125

126
Constants for mapping between JavaScript property names and HTML attribute names.
127

128
```typescript { .api }
129
/**
130
 * Mapping from JavaScript property names to HTML attribute names
131
 * Used when converting props to attributes
132
 */
133
const propsToAttrMap: Record<string, string | undefined>;
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
import { 
140
  isHTMLTag, isSVGTag, isVoidTag,
141
  isBooleanAttr, includeBooleanAttr,
142
  isSSRSafeAttrName, isKnownHtmlAttr,
143
  isRenderableAttrValue, propsToAttrMap
144
} from "@vue/shared";
145

146
// Element tag validation (compiler use)
147
if (__DEV__) {
148
  console.log(isHTMLTag("div")); // true
149
  console.log(isHTMLTag("custom-element")); // false
150
  
151
  console.log(isSVGTag("circle")); // true
152
  console.log(isSVGTag("div")); // false
153
  
154
  console.log(isVoidTag("br")); // true
155
  console.log(isVoidTag("div")); // false
156
}
157

158
// Boolean attribute handling
159
function handleBooleanAttr(name: string, value: unknown) {
160
  if (isBooleanAttr(name)) {
161
    // Boolean attributes like "disabled", "checked", "hidden"
162
    if (includeBooleanAttr(value)) {
163
      return name; // Include attribute without value
164
    }
165
    return null; // Omit attribute
166
  }
167
  return `${name}="${value}"`; // Regular attribute with value
168
}
169

170
// Examples of boolean attribute behavior
171
console.log(includeBooleanAttr(true)); // true
172
console.log(includeBooleanAttr("")); // true (empty string counts as truthy for boolean attrs)
173
console.log(includeBooleanAttr(false)); // false
174
console.log(includeBooleanAttr(null)); // false
175

176
// SSR safety checking
177
function validateAttributeName(name: string) {
178
  if (!isSSRSafeAttrName(name)) {
179
    console.error(`Unsafe attribute name: ${name}`);
180
    return false;
181
  }
182
  return true;
183
}
184

185
// Valid names
186
validateAttributeName("class"); // true
187
validateAttributeName("data-value"); // true
188

189
// Invalid names (contain unsafe characters)
190
validateAttributeName("on>click"); // false (logs error)
191
validateAttributeName("style="); // false (logs error)
192

193
// Known attribute checking
194
function isKnownAttribute(attrName: string, tagType: 'html' | 'svg' | 'mathml') {
195
  switch (tagType) {
196
    case 'html':
197
      return isKnownHtmlAttr(attrName);
198
    case 'svg':
199
      return isKnownSvgAttr(attrName);
200
    case 'mathml':
201
      return isKnownMathMLAttr(attrName);
202
  }
203
}
204

205
// Attribute value validation
206
function canRenderAttribute(value: unknown): boolean {
207
  return isRenderableAttrValue(value);
208
}
209

210
console.log(canRenderAttribute("string")); // true
211
console.log(canRenderAttribute(42)); // true
212
console.log(canRenderAttribute(true)); // true
213
console.log(canRenderAttribute(null)); // false
214
console.log(canRenderAttribute(undefined)); // false
215
console.log(canRenderAttribute({})); // false
216

217
// Property to attribute mapping
218
function getAttributeName(propName: string): string {
219
  return propsToAttrMap[propName] || propName;
220
}
221

222
console.log(getAttributeName("className")); // "class"
223
console.log(getAttributeName("htmlFor")); // "for"
224
console.log(getAttributeName("acceptCharset")); // "accept-charset"
225
console.log(getAttributeName("customProp")); // "customProp" (no mapping)
226
```
227

228
### Element Coverage
229

230
The validation functions recognize comprehensive sets of elements:
231

232
**HTML Elements**: All standard HTML5 elements including semantic elements, form controls, media elements, and structural elements.
233

234
**SVG Elements**: Complete SVG specification including shapes, filters, gradients, animations, and text elements.
235

236
**MathML Elements**: Mathematical notation elements for scientific and mathematical expressions.
237

238
**Void Elements**: Self-closing elements that cannot have children (`br`, `img`, `input`, `meta`, etc.).
239

240
### Boolean Attribute Types
241

242
**Special Boolean Attributes**: Have different JavaScript property names:
243
- `itemscope`, `allowfullscreen`, `formnovalidate`, `ismap`, `nomodule`, `novalidate`, `readonly`
244

245
**Regular Boolean Attributes**: Standard HTML boolean attributes:
246
- `async`, `autofocus`, `autoplay`, `checked`, `disabled`, `hidden`, `multiple`, `required`, `selected`, etc.
247

248
### Performance Considerations
249

250
- All validation functions use optimized `makeMap` for O(1) lookup performance
251
- Functions are marked for tree-shaking when not used in production
252
- Validation cache is used for SSR attribute name checking to avoid repeated validation