0
# Web Components
1

2
Core custom element functionality for building reusable web components with lifecycle management, Shadow DOM, and attribute synchronization.
3

4
## Capabilities
5

6
### FASTElement Base Class
7

8
The base class for all FAST custom elements, extending HTMLElement with reactive properties, Shadow DOM support, and lifecycle management.
9

10
```typescript { .api }
11
/**
12
 * The base class for FAST custom elements
13
 * Provides reactive property system, Shadow DOM management, and element lifecycle
14
 */
15
class FASTElement extends HTMLElement {
16
  /** The element controller that manages lifecycle and rendering */
17
  readonly $fastController: ElementController;
18
  
19
  /** Emits a custom HTML event */
20
  $emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): boolean | void;
21
  
22
  /** Called when the element is inserted into the DOM */
23
  connectedCallback(): void;
24
  
25
  /** Called when the element is removed from the DOM */
26
  disconnectedCallback(): void;
27
  
28
  /** Called when an observed attribute changes */
29
  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
30
}
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
import { FASTElement, customElement, attr, html } from "@microsoft/fast-element";
37

38
@customElement("my-button")
39
export class MyButton extends FASTElement {
40
  @attr disabled: boolean = false;
41
  @attr label: string = "Click me";
42
  
43
  connectedCallback() {
44
    super.connectedCallback();
45
    console.log("Button connected to DOM");
46
  }
47
  
48
  private handleClick() {
49
    if (!this.disabled) {
50
      this.$emit("button-click", { label: this.label });
51
    }
52
  }
53
}
54
```
55

56
### Custom Element Decorator
57

58
Decorator function for defining custom elements with templates, styles, and configuration options.
59

60
```typescript { .api }
61
/**
62
 * Decorator for defining custom elements
63
 * @param definition - Element definition with name, template, styles, etc.
64
 * @returns Class decorator that registers the custom element
65
 */
66
function customElement(definition: PartialFASTElementDefinition): ClassDecorator;
67

68
/**
69
 * Decorator with element name only
70
 * @param name - The custom element tag name
71
 * @returns Class decorator that registers the custom element
72
 */
73
function customElement(name: string): ClassDecorator;
74

75
interface PartialFASTElementDefinition {
76
  /** The custom element tag name */
77
  name: string;
78
  /** The template for the element */
79
  template?: ViewTemplate;
80
  /** The styles for the element */
81
  styles?: ElementStyles | ElementStyles[];
82
  /** Shadow DOM options */
83
  shadowOptions?: ShadowRootOptions | null;
84
  /** Element registry for dependency injection */
85
  elementOptions?: ElementDefinitionOptions;
86
}
87

88
interface ShadowRootOptions {
89
  mode: "open" | "closed";
90
  delegatesFocus?: boolean;
91
  slotAssignment?: "manual" | "named";
92
}
93
```
94

95
**Usage Examples:**
96

97
```typescript
98
import { FASTElement, customElement, html, css } from "@microsoft/fast-element";
99

100
// With full definition
101
@customElement({
102
  name: "user-card",
103
  template: html<UserCard>`
104
    <div class="card">
105
      <h3>${x => x.name}</h3>
106
      <p>${x => x.email}</p>
107
    </div>
108
  `,
109
  styles: css`
110
    .card {
111
      border: 1px solid #ccc;
112
      padding: 16px;
113
      border-radius: 8px;
114
    }
115
  `,
116
  shadowOptions: {
117
    mode: "open",
118
    delegatesFocus: true
119
  }
120
})
121
export class UserCard extends FASTElement {
122
  @attr name: string = "";
123
  @attr email: string = "";
124
}
125

126
// With name only
127
@customElement("simple-card")
128
export class SimpleCard extends FASTElement {
129
  // Template and styles can be set via static properties
130
  static template = html`<slot></slot>`;
131
  static styles = css`:host { display: block; }`;
132
}
133
```
134

135
### Element Controller
136

137
Internal controller that manages element lifecycle, rendering, and property synchronization.
138

139
```typescript { .api }
140
/**
141
 * Controller that manages FAST element lifecycle and rendering
142
 */
143
class ElementController {
144
  /** The element being controlled */
145
  readonly element: HTMLElement;
146
  
147
  /** The element definition */
148
  readonly definition: FASTElementDefinition;
149
  
150
  /** Whether the element is connected to the DOM */
151
  readonly isConnected: boolean;
152
  
153
  /** The element's view if it has a template */
154
  readonly view?: HTMLView;
155
  
156
  /** Connect the element (called by connectedCallback) */
157
  connect(): void;
158
  
159
  /** Disconnect the element (called by disconnectedCallback) */
160
  disconnect(): void;
161
  
162
  /** Handle attribute changes */
163
  onAttributeChangedCallback(name: string, oldValue: string, newValue: string): void;
164
  
165
  /** Add a view behavior */
166
  addBehavior(behavior: ViewBehavior): void;
167
  
168
  /** Remove a view behavior */
169
  removeBehavior(behavior: ViewBehavior, force?: boolean): void;
170
}
171

172
/**
173
 * Strategy for creating element controllers
174
 */
175
interface ElementControllerStrategy {
176
  /** Create a controller for the given element */
177
  create(element: HTMLElement, definition: FASTElementDefinition): ElementController;
178
}
179
```
180

181
### Element Definition
182

183
Complete definition of a custom element including its configuration and metadata.
184

185
```typescript { .api }
186
/**
187
 * Complete definition of a FAST custom element
188
 */
189
class FASTElementDefinition {
190
  /** The custom element tag name */
191
  readonly name: string;
192
  
193
  /** The element type/constructor */
194
  readonly type: Constructable<HTMLElement>;
195
  
196
  /** Attribute definitions */
197
  readonly attributes: AttributeDefinition[];
198
  
199
  /** Property definitions */
200
  readonly propertyLookup: Record<string, AttributeDefinition>;
201
  
202
  /** Attribute lookup by name */
203
  readonly attributeLookup: Record<string, AttributeDefinition>;
204
  
205
  /** Template for the element */
206
  readonly template?: ViewTemplate;
207
  
208
  /** Styles for the element */
209
  readonly styles?: ElementStyles;
210
  
211
  /** Shadow DOM options */
212
  readonly shadowOptions?: ShadowRootOptions;
213
  
214
  /** Element definition options */
215
  readonly elementOptions?: ElementDefinitionOptions;
216
  
217
  /** Define the custom element */
218
  define(registry?: CustomElementRegistry): this;
219
}
220

221
interface TemplateOptions {
222
  /** Template compilation strategy */
223
  strategy?: CompilationStrategy;
224
}
225
```
226

227
### Element Registry
228

229
Registry for managing element definitions and dependency injection.
230

231
```typescript { .api }
232
/**
233
 * Registry for FAST element definitions
234
 */
235
const fastElementRegistry: {
236
  /** Register an element definition */
237
  register(definition: FASTElementDefinition): void;
238
  
239
  /** Get an element definition by name */
240
  getByName(name: string): FASTElementDefinition | undefined;
241
  
242
  /** Get all registered definitions */
243
  getAll(): FASTElementDefinition[];
244
};
245

246
interface TypeRegistry {
247
  /** Register a type with the registry */
248
  register<T>(key: any, value: T): void;
249
  
250
  /** Get a type from the registry */
251
  get<T>(key: any): T | undefined;
252
}
253
```
254

255
**Usage Examples:**
256

257
```typescript
258
import { FASTElement, customElement, fastElementRegistry } from "@microsoft/fast-element";
259

260
// Register an element
261
@customElement("my-element")
262
class MyElement extends FASTElement {}
263

264
// Check if element is registered
265
const definition = fastElementRegistry.getByName("my-element");
266
if (definition) {
267
  console.log("Element is registered");
268
}
269

270
// Get all registered elements
271
const allDefinitions = fastElementRegistry.getAll();
272
console.log(`${allDefinitions.length} elements registered`);
273
```
274

275
### Hydratable Element Controller
276

277
Specialized controller for server-side rendering and hydration scenarios.
278

279
```typescript { .api }
280
/**
281
 * Element controller that supports SSR hydration
282
 */
283
class HydratableElementController extends ElementController {
284
  /** Whether this controller supports hydration */
285
  readonly needsHydration: boolean;
286
  
287
  /** Hydrate the element from server-rendered content */
288
  hydrate(): void;
289
}
290
```
291

292
## Types
293

294
```typescript { .api }
295
interface ElementDefinitionOptions {
296
  /** Base element type to extend */
297
  extends?: string;
298
}
299

300
interface ViewBehavior {
301
  /** Bind the behavior to a source */
302
  bind(source: any, context: ExecutionContext): void;
303
  
304
  /** Unbind the behavior */
305
  unbind(source: any): void;
306
}
307

308
interface FASTGlobal {
309
  /** Global element registry */
310
  registry: TypeRegistry;
311
  
312
  /** Warning function */
313
  warn(message: string): void;
314
  
315
  /** Error function */
316
  error(message: string): void;
317
}
318
```