0
# Mounting and Lifecycle
1

2
Core functionality for mounting components to DOM elements and managing their lifecycle. Components go through mount, update, and unmount phases with corresponding lifecycle hooks.
3

4
## Capabilities
5

6
### Mount Components
7

8
Mounts registered components to DOM elements, creating component instances.
9

10
```typescript { .api }
11
/**
12
 * Mounting function for globally registered components
13
 * @param selector - CSS selector string or HTMLElement to mount to
14
 * @param initialProps - Initial properties to pass to the component
15
 * @param componentName - Optional specific component name to mount
16
 * @returns Array of mounted component instances
17
 */
18
function mount<Props extends DefaultProps, State extends DefaultState>(
19
  selector: string | HTMLElement,
20
  initialProps?: Props,
21
  componentName?: string
22
): RiotComponent<Props, State>[];
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
import { mount, register } from "riot";
29

30
// Mount all registered components matching their tag names
31
const components = mount("my-component");
32

33
// Mount with initial props
34
const components = mount("my-timer", { startTime: 10 });
35

36
// Mount to specific element
37
const element = document.getElementById("app");
38
const components = mount(element, { title: "Hello World" });
39

40
// Mount specific component to elements
41
const components = mount(".widget", { theme: "dark" }, "my-widget");
42
```
43

44
### Unmount Components
45

46
Unmounts component instances from DOM elements, cleaning up resources and optionally preserving the root element.
47

48
```typescript { .api }
49
/**
50
 * Unmounting helper function for components mounted to DOM nodes
51
 * @param selector - CSS selector string or HTMLElement to unmount from
52
 * @param keepRootElement - If true, preserves the root DOM element
53
 * @returns Array of DOM elements that were unmounted
54
 */
55
function unmount(
56
  selector: string | HTMLElement,
57
  keepRootElement?: boolean
58
): HTMLElement[];
59
```
60

61
**Usage Examples:**
62

63
```javascript
64
import { unmount } from "riot";
65

66
// Unmount all components in matching elements
67
const elements = unmount("my-component");
68

69
// Unmount but keep the DOM element
70
const elements = unmount(".widgets", true);
71

72
// Unmount from specific element
73
const element = document.getElementById("app");
74
const elements = unmount(element);
75
```
76

77
## Component Lifecycle
78

79
Components follow a predictable lifecycle with hooks for each phase:
80

81
### Lifecycle Methods
82

83
```typescript { .api }
84
interface RiotComponent<Props = DefaultProps, State = DefaultState> {
85
  /** Called before component is mounted to DOM */
86
  onBeforeMount?(props: Props, state: State): void;
87
  
88
  /** Called after component is mounted to DOM */
89
  onMounted?(props: Props, state: State): void;
90
  
91
  /** Called before component state/props update */
92
  onBeforeUpdate?(props: Props, state: State): void;
93
  
94
  /** Called after component state/props update */
95
  onUpdated?(props: Props, state: State): void;
96
  
97
  /** Called before component is unmounted from DOM */
98
  onBeforeUnmount?(props: Props, state: State): void;
99
  
100
  /** Called after component is unmounted from DOM */
101
  onUnmounted?(props: Props, state: State): void;
102
  
103
  /** Optional method to control when component should update */
104
  shouldUpdate?(newProps: Props, oldProps: Props): boolean;
105
}
106
```
107

108
### Component Instance Methods
109

110
Once mounted, component instances provide methods for state management:
111

112
```typescript { .api }
113
interface RiotComponent<Props = DefaultProps, State = DefaultState> {
114
  /** Mount component to DOM element */
115
  mount(
116
    element: HTMLElement,
117
    initialState?: State,
118
    parentScope?: object
119
  ): RiotComponent<Props, State>;
120
  
121
  /** Update component state and re-render */
122
  update(
123
    newState?: Partial<State>,
124
    parentScope?: object
125
  ): RiotComponent<Props, State>;
126
  
127
  /** Unmount component from DOM */
128
  unmount(keepRootElement?: boolean): RiotComponent<Props, State>;
129
  
130
  /** Query single element within component root */
131
  $(selector: string): Element | null;
132
  
133
  /** Query multiple elements within component root */
134
  $$(selector: string): Element[];
135
}
136
```
137

138
### Component Properties
139

140
Component instances have read-only properties and mutable state:
141

142
```typescript { .api }
143
interface RiotComponent<Props = DefaultProps, State = DefaultState> {
144
  /** Read-only props passed to component */
145
  readonly props: Props;
146
  
147
  /** Root DOM element of the component */
148
  readonly root: HTMLElement;
149
  
150
  /** Component name (if registered) */
151
  readonly name?: string;
152
  
153
  /** Slot data for child content */
154
  readonly slots: TagSlotData[];
155
  
156
  /** Mutable component state */
157
  state: State;
158
  
159
  /** Optional child component mappings */
160
  components?: RiotComponentsMap;
161
}
162
```
163

164
**Usage Example:**
165

166
```javascript
167
const componentDef = {
168
  onBeforeMount(props, state) {
169
    this.state = { count: props.initial || 0 };
170
  },
171
  
172
  onMounted(props, state) {
173
    console.log("Component mounted with state:", state);
174
  },
175
  
176
  increment() {
177
    this.update({ count: this.state.count + 1 });
178
  },
179
  
180
  onBeforeUpdate(props, state) {
181
    console.log("Updating from", this.state.count, "to", state.count);
182
  },
183
  
184
  onUnmounted() {
185
    console.log("Component cleaned up");
186
  }
187
};
188
```
189

190
## Types
191

192
```typescript { .api }
193
type DefaultProps = Record<PropertyKey, any>;
194
type DefaultState = Record<PropertyKey, any>;
195

196
type TagSlotData = {
197
  id: string;
198
  html: string;
199
  bindings: BindingData[];
200
};
201

202
type RiotComponentsMap = {
203
  [key: string]: RiotComponentWrapper<RiotComponent>;
204
};
205
```