0
# FAST Element
1

2
FAST Element is a lightweight, performant library for building standards-compliant Web Components that work across all major browsers and can be used with any front-end framework or without one. It provides a comprehensive toolkit for creating reusable UI components with modern TypeScript support, featuring reactive data binding, efficient templating with tagged template literals, dependency injection, state management, and SSR hydration capabilities.
3

4
## Package Information
5

6
- **Package Name**: @microsoft/fast-element
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @microsoft/fast-element`
10

11
## Core Imports
12

13
```typescript
14
// Main functionality
15
import { FASTElement, customElement, attr, html, css, observable } from "@microsoft/fast-element";
16

17
// Specialized imports
18
import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
19
import { signal, Signal } from "@microsoft/fast-element/binding/signal.js";
20
import { state, reactive, watch } from "@microsoft/fast-element/state.js";
21
import { Context } from "@microsoft/fast-element/context.js";
22
import { DI, inject, singleton, transient } from "@microsoft/fast-element/di.js";
23
import { fixture, timeout } from "@microsoft/fast-element/testing.js";
24
```
25

26
For CommonJS:
27

28
```javascript
29
const { FASTElement, customElement, attr, html, css, observable } = require("@microsoft/fast-element");
30
```
31

32
## Basic Usage
33

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

37
// Define styles
38
const styles = css`
39
  :host {
40
    display: block;
41
    padding: 16px;
42
    background: var(--background-color, #f0f0f0);
43
  }
44
  
45
  .greeting {
46
    font-size: 18px;
47
    color: var(--text-color, #333);
48
  }
49
`;
50

51
// Define template
52
const template = html<GreetingCard>`
53
  <div class="greeting">
54
    Hello, ${x => x.name}!
55
  </div>
56
`;
57

58
// Define custom element
59
@customElement({
60
  name: "greeting-card",
61
  template,
62
  styles
63
})
64
export class GreetingCard extends FASTElement {
65
  @attr name: string = "World";
66
}
67
```
68

69
## Architecture
70

71
FAST Element is built around several key architectural components:
72

73
- **Reactive Observable System**: Memory-efficient property observation with automatic dependency tracking
74
- **Template System**: HTML template literals with efficient compilation and binding
75
- **Component Lifecycle**: Custom element base class with Shadow DOM and attribute management  
76
- **Binding System**: One-way, two-way, and event bindings with type safety
77
- **CSS System**: Composable styles with CSS-in-JS support and design tokens
78
- **Dependency Injection**: Full DI container with decorators and service location
79
- **State Management**: Reactive state with computed values and change watchers
80
- **SSR Support**: Server-side rendering with client-side hydration
81

82
## Capabilities
83

84
### Web Components
85

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

88
```typescript { .api }
89
class FASTElement extends HTMLElement {
90
  readonly $fastController: ElementController;
91
  
92
  $emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): boolean | void;
93
  connectedCallback(): void;
94
  disconnectedCallback(): void;
95
  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
96
}
97

98
function customElement(definition: PartialFASTElementDefinition): ClassDecorator;
99
function customElement(nameOrDefinition: string | PartialFASTElementDefinition): ClassDecorator;
100
```
101

102
[Web Components](./web-components.md)
103

104
### HTML Templates
105

106
Template system using tagged template literals with efficient compilation, directive support, and reactive binding capabilities.
107

108
```typescript { .api }
109
function html<TSource = any, TParent = any>(
110
  strings: TemplateStringsArray,
111
  ...values: TemplateValue<TSource, TParent>[]
112
): ViewTemplate<TSource, TParent>;
113

114
class ViewTemplate<TSource = any, TParent = any> {
115
  create(host?: Element): HTMLView<TSource, TParent>;
116
  render(source: TSource, host: Element | string, hostBindingTarget?: Element): HTMLView<TSource, TParent>;
117
}
118
```
119

120
[HTML Templates](./html-templates.md)
121

122
### CSS Styling
123

124
Composable CSS system with tagged template literals, design tokens, and efficient style application strategies.
125

126
```typescript { .api }
127
function css(strings: TemplateStringsArray, ...values: CSSValue[]): ElementStyles;
128

129
class ElementStyles {
130
  behaviors?: HostBehavior[];
131
  
132
  addStylesTo(target: StyleTarget): void;
133
  removeStylesFrom(target: StyleTarget): void;
134
}
135
```
136

137
[CSS Styling](./css-styling.md)
138

139
### Data Binding
140

141
Reactive data binding system supporting one-way, two-way, and event bindings with automatic dependency tracking and efficient updates.
142

143
```typescript { .api }
144
function oneWay<T = any>(
145
  expression: Expression<T>,
146
  policy?: DOMPolicy,
147
  isBindingVolatile?: boolean
148
): Binding<T>;
149

150
function listener<T = any>(
151
  expression: Expression<T>,
152
  options?: AddEventListenerOptions
153
): Binding<T>;
154

155
class Binding<TSource = any, TReturn = any, TParent = any> {
156
  evaluate(source: TSource, context: ExecutionContext<TParent>): TReturn;
157
}
158
```
159

160
[Data Binding](./data-binding.md)
161

162
### Observable System
163

164
Memory-efficient observable system with automatic dependency tracking, batch updates, and array observation capabilities.
165

166
```typescript { .api }
167
function observable<T, K extends keyof T>(target: T, nameOrAccessor: K): void;
168
function observable<T, K extends keyof T>(target: T, nameOrAccessor: K, descriptor: PropertyDescriptor): PropertyDescriptor;
169

170
const Observable: {
171
  binding<T>(evaluate: () => T, observer: ExpressionObserver, isVolatile?: boolean): ExpressionObserver<any, T>;
172
  track<T>(target: T, propertyName: keyof T): void;
173
  notify(source: any, args: any): void;
174
};
175
```
176

177
[Observable System](./observable-system.md)
178

179
### Template Directives
180

181
Built-in template directives for common patterns like conditionals, loops, references, and DOM node observation.
182

183
```typescript { .api }
184
function when<TSource = any, TParent = any>(
185
  expression: Expression<any, TSource, TParent>,
186
  templateOrTemplateExpression: ViewTemplate<TSource, TParent> | Expression<ViewTemplate<TSource, TParent>, TSource, TParent>
187
): HTMLDirective;
188

189
function repeat<TSource = any, TParent = any>(
190
  expression: Expression<any[], TSource, TParent>, 
191
  template: ViewTemplate<any, TSource>,
192
  options?: RepeatOptions
193
): RepeatDirective<TSource, TParent>;
194

195
function ref<TSource = any, TParent = any>(propertyName: keyof TSource): RefDirective;
196
```
197

198
[Template Directives](./template-directives.md)
199

200
### Attributes
201

202
Attribute system with automatic type conversion, reflection options, and custom converters for seamless property-attribute synchronization.
203

204
```typescript { .api }
205
function attr(config?: AttributeConfiguration): PropertyDecorator;
206
function attr(target: {}, property: string | symbol): void;
207

208
interface AttributeConfiguration {
209
  attribute?: string;
210
  mode?: AttributeMode;
211
  converter?: ValueConverter;
212
}
213

214
const booleanConverter: ValueConverter;
215
const nullableBooleanConverter: ValueConverter;  
216
const nullableNumberConverter: ValueConverter;
217
```
218

219
[Attributes](./attributes.md)
220

221
### State Management
222

223
Reactive state management with reactive objects, computed values, and change watchers for complex application state.
224

225
```typescript { .api }
226
function state<T>(value: T, options?: StateOptions<T>): State<T>;
227
function computedState<T>(compute: ComputedInitializer<T>): ComputedState<T>;
228
function reactive<T extends object>(target: T): T;
229
function watch<T>(target: T, callback: (source: T, args: any) => void): void;
230

231
interface State<T> {
232
  readonly value: T;
233
  set(value: T): void;
234
}
235
```
236

237
[State Management](./state-management.md)
238

239
### Dependency Injection
240

241
Full-featured dependency injection container with decorators, service registration, and hierarchical resolution.
242

243
```typescript { .api }
244
function inject(...keys: Key[]): ParameterDecorator | PropertyDecorator;
245
function singleton<T extends Constructable>(RegisterTarget?: T): RegisterSelf<T>;
246
function transient<T extends Constructable>(RegisterTarget?: T): RegisterSelf<T>;
247

248
interface Container {
249
  get<K extends Key>(key: K): Resolved<K>;
250
  register(...registrations: Registration[]): Container;
251
  createChild(config?: ContainerConfiguration): Container;
252
}
253

254
const DI: {
255
  createContainer(config?: ContainerConfiguration): Container;
256
  getOrCreateDOMContainer(node?: Node): DOMContainer;
257
};
258
```
259

260
[Dependency Injection](./dependency-injection.md)
261

262
### Context System  
263

264
Context protocol for sharing data and services across component trees using events and dependency injection integration.
265

266
```typescript { .api }
267
interface FASTContext<T> extends ContextDecorator<T> {
268
  get(target: EventTarget): T;
269
  provide(target: EventTarget, value: T): void;
270
  request(target: EventTarget, callback: ContextCallback<T>, multiple?: boolean): void;
271
}
272

273
const Context: {
274
  create<T>(name: string, initialValue?: T): FASTContext<T>;
275
  setRequestStrategy(strategy: FASTContextRequestStrategy): void;
276
};
277
```
278

279
[Context System](./context-system.md)
280

281
### SSR Hydration
282

283
Server-side rendering support with hydration capabilities for fast initial page loads and SEO optimization.
284

285
```typescript { .api }
286
const HydrationMarkup: {
287
  attributeMarkerName: string;
288
  contentBindingStartMarker(index: number, targetNodeId: string): string;
289
  contentBindingEndMarker(index: number): string;
290
};
291

292
function isHydratable(obj: any): obj is { [Hydratable]: true };
293

294
const Hydratable: unique symbol;
295
```
296

297
[SSR Hydration](./ssr-hydration.md)
298

299
### Testing Utilities
300

301
Testing utilities for creating component fixtures, managing async operations, and integration testing.
302

303
```typescript { .api }
304
function fixture<T extends HTMLElement = HTMLElement>(
305
  nameOrMarkupOrTemplate: string | ViewTemplate,
306
  options?: FixtureOptions
307
): Promise<Fixture<T>>;
308

309
function uniqueElementName(): string;
310
function timeout(duration: number): Promise<void>;
311

312
interface Fixture<T extends HTMLElement = HTMLElement> {
313
  document: Document;
314
  template: ViewTemplate;
315
  element: T;
316
  parent: HTMLElement;
317
  connect(): Promise<void>;
318
  disconnect(): Promise<void>;
319
}
320
```
321

322
[Testing Utilities](./testing-utilities.md)
323

324
### Utilities
325

326
DOM utilities and component orchestration for advanced scenarios involving Shadow DOM navigation and view behavior management.
327

328
```typescript { .api }
329
function composedParent<T extends HTMLElement>(element: T): HTMLElement | null;
330
function composedContains(reference: HTMLElement, test: HTMLElement): boolean;
331

332
class UnobservableMutationObserver extends MutationObserver {
333
  constructor(callback: MutationCallback);
334
  observe(target: Node, options?: MutationObserverInit): void;
335
  unobserve(target: Node): void;
336
}
337

338
const ViewBehaviorOrchestrator: {
339
  create<TSource = any, TParent = any>(source: TSource): ViewBehaviorOrchestrator<TSource, TParent>;
340
};
341
```
342

343
[Utilities](./utilities.md)
344

345
## Types
346

347
```typescript { .api }
348
interface Constructable<T = {}> {
349
  new (...args: any[]): T;
350
}
351

352
interface Disposable {
353
  dispose(): void;
354
}
355

356
interface ExecutionContext<TParent = any> {
357
  index: number;
358
  length: number;
359
  parent: TParent;
360
  parentContext: ExecutionContext<TParent>;
361
}
362

363
type Expression<TReturn = any, TSource = any, TParent = any> = 
364
  | ((source: TSource, context: ExecutionContext<TParent>) => TReturn)
365
  | string;
366

367
interface Subscriber {
368
  handleChange(source: any, args: any): void;
369
}
370

371
interface ViewTemplate<TSource = any, TParent = any> {
372
  create(host?: Element): HTMLView<TSource, TParent>;
373
  render(source: TSource, host: Element | string, hostBindingTarget?: Element): HTMLView<TSource, TParent>;
374
}
375

376
interface HTMLView<TSource = any, TParent = any> {
377
  firstChild: Node | null;
378
  lastChild: Node | null;
379
  bind(source: TSource, context?: ExecutionContext<TParent>): void;
380
  unbind(): void;
381
  appendTo(parent: Node): void;
382
  removeFrom(parent: Node): void;
383
}
384

385
interface ElementStyles {
386
  behaviors?: HostBehavior[];
387
  addStylesTo(target: StyleTarget): void;
388
  removeStylesFrom(target: StyleTarget): void;
389
}
390

391
interface Binding<TSource = any, TReturn = any, TParent = any> {
392
  evaluate(source: TSource, context: ExecutionContext<TParent>): TReturn;
393
}
394

395
type Key = string | object | Interface | Constructable | null;
396
type Resolved<K> = K extends Constructable<infer T> ? T : K extends Interface<infer T> ? T : K;
397

398
interface Interface<T = any> {
399
  readonly name: string;
400
  readonly $isInterface: true;
401
}
402
```