0
# Riot.js
1

2
Riot.js is a simple and elegant component-based UI library that brings custom components to all modern browsers. It features a concise HTML-like syntax, one-way data flow, and high performance through pre-compiled expressions with minimal DOM manipulation.
3

4
## Package Information
5

6
- **Package Name**: riot
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install riot`
10

11
## Core Imports
12

13
```javascript
14
import { mount, register, component } from "riot";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { mount, register, component } = require("riot");
21
```
22

23
Compiler build (includes compilation capabilities):
24

25
```javascript
26
import { mount, register, compile } from "riot+compiler";
27
```
28

29
## Basic Usage
30

31
```javascript
32
import { register, mount } from "riot";
33

34
// Register a component (typically done by the build process)
35
register("my-timer", {
36
  css: "my-timer { display: block; }",
37
  template: (template, expressionTypes, bindingTypes) => 
38
    template("<p>Seconds: { state.time }</p>", [
39
      // Template bindings would be here
40
    ]),
41
  exports: {
42
    onBeforeMount() {
43
      this.state = { time: 0 };
44
      this.timer = setInterval(() => {
45
        this.update({ time: this.state.time + 1 });
46
      }, 1000);
47
    },
48
    onUnmounted() {
49
      clearInterval(this.timer);
50
    }
51
  }
52
});
53

54
// Mount the component
55
const components = mount("my-timer");
56
```
57

58
## Architecture
59

60
Riot.js is built around several key concepts:
61

62
- **Component Registration**: Global registry system for component definitions
63
- **Component Lifecycle**: Mount, update, and unmount phases with lifecycle hooks
64
- **Template System**: Pre-compiled template functions with expression bindings
65
- **Plugin System**: Component enhancer functions for extending functionality
66
- **Pure Components**: Lightweight components without lifecycle management
67
- **Compiler Integration**: Optional runtime compilation of component templates
68

69
## Capabilities
70

71
### Component Registration
72

73
System for registering and managing component definitions in a global registry.
74

75
```typescript { .api }
76
function register<Props, State>(
77
  componentName: string,
78
  wrapper: RiotComponentWrapper<RiotComponent<Props, State>>
79
): RegisteredComponentsMap;
80

81
function unregister(componentName: string): RegisteredComponentsMap;
82
```
83

84
[Component Registration](./component-registration.md)
85

86
### Mounting and Lifecycle
87

88
Core functionality for mounting components to DOM elements and managing their lifecycle.
89

90
```typescript { .api }
91
function mount<Props, State>(
92
  selector: string | HTMLElement,
93
  initialProps?: Props,
94
  componentName?: string
95
): RiotComponent<Props, State>[];
96

97
function unmount(
98
  selector: string | HTMLElement,
99
  keepRootElement?: boolean
100
): HTMLElement[];
101
```
102

103
[Mounting and Lifecycle](./mounting-lifecycle.md)
104

105
### Component Factory
106

107
Direct component creation without global registration, useful for dynamic components.
108

109
```typescript { .api }
110
function component<Props, State, Component extends RiotComponent>(
111
  wrapper: RiotComponentWrapper<Component>
112
): (el: HTMLElement, initialProps?: Props, meta?: ComponentMeta) => Component;
113
```
114

115
[Component Factory](./component-factory.md)
116

117
### Plugin System
118

119
Component enhancement system for adding cross-cutting functionality to all components.
120

121
```typescript { .api }
122
function install(plugin: ComponentEnhancer): InstalledPluginsSet;
123
function uninstall(plugin: ComponentEnhancer): InstalledPluginsSet;
124
```
125

126
[Plugin System](./plugin-system.md)
127

128
### Pure Components
129

130
Lightweight component pattern for simple, stateless components without full lifecycle management.
131

132
```typescript { .api }
133
function pure<InitialProps, Context, FactoryFunction>(
134
  func: FactoryFunction
135
): FactoryFunction;
136
```
137

138
[Pure Components](./pure-components.md)
139

140
### Compilation (riot+compiler build)
141

142
Runtime compilation capabilities for compiling riot components from templates and URLs.
143

144
```typescript { .api }
145
function compile(options?: CompileOptions): Promise<void>;
146
function compileFromString(string: string, options?: CompileOptions): CompilationResult;
147
function compileFromUrl(url: string, options?: CompileOptions): Promise<CompilationResult>;
148
```
149

150
[Compilation](./compilation.md)
151

152
### Utilities
153

154
Helper functions, version information, and internal API access for advanced use cases.
155

156
```typescript { .api }
157
function withTypes<Component>(component: Component): Component;
158
const version: string;
159
const __: InternalAPI;
160
```
161

162
[Utilities](./utilities.md)
163

164
## Core Types
165

166
```typescript { .api }
167
interface RiotComponent<Props = DefaultProps, State = DefaultState> {
168
  readonly props: Props;
169
  readonly root: HTMLElement;
170
  readonly name?: string;
171
  readonly slots: TagSlotData[];
172
  state: State;
173
  components?: RiotComponentsMap;
174

175
  mount(
176
    element: HTMLElement,
177
    initialState?: State,
178
    parentScope?: object
179
  ): RiotComponent<Props, State>;
180
  
181
  update(
182
    newState?: Partial<State>,
183
    parentScope?: object
184
  ): RiotComponent<Props, State>;
185
  
186
  unmount(keepRootElement?: boolean): RiotComponent<Props, State>;
187

188
  $(selector: string): Element | null;
189
  $$(selector: string): Element[];
190

191
  shouldUpdate?(newProps: Props, oldProps: Props): boolean;
192
  onBeforeMount?(props: Props, state: State): void;
193
  onMounted?(props: Props, state: State): void;
194
  onBeforeUpdate?(props: Props, state: State): void;
195
  onUpdated?(props: Props, state: State): void;
196
  onBeforeUnmount?(props: Props, state: State): void;
197
  onUnmounted?(props: Props, state: State): void;
198
}
199

200
interface RiotComponentWrapper<Component> {
201
  readonly css?: string | null;
202
  readonly exports?: RiotComponentFactoryFunction<Component> | Component | null;
203
  readonly name?: string | null;
204
  template?(
205
    template: TemplateFunction,
206
    expressionTypes: ExpressionTypes,
207
    bindingTypes: BindingTypes,
208
    getComponent: GetComponentFunction
209
  ): TemplateChunk<Component> | null;
210
}
211

212
interface RiotPureComponent<Context = object> {
213
  mount(element: HTMLElement, context?: Context): void;
214
  update(context?: Context): void;
215
  unmount(keepRootElement: boolean): void;
216
}
217

218
type DefaultProps = Record<PropertyKey, any>;
219
type DefaultState = Record<PropertyKey, any>;
220
type ComponentEnhancer = <Props, State>(
221
  component: RiotComponent<Props, State>
222
) => RiotComponent<Props, State>;
223
```