0
# Event System
1

2
Event handling system for responding to positioning changes and tether lifecycle events. Tether extends the Evented base class to provide comprehensive event management capabilities including registration, removal, and triggering of custom events.
3

4
## Capabilities
5

6
### Event Registration
7

8
Register event handlers for tether events.
9

10
```javascript { .api }
11
/**
12
 * Adds an event listener to the tether instance
13
 * @param event - Event name to listen for
14
 * @param handler - Function to call when event is triggered
15
 * @param ctx - Context (this value) for the handler function
16
 * @param once - Whether to execute the handler only once
17
 * @returns The tether instance for method chaining
18
 */
19
on(event: string, handler: Function, ctx?: any, once?: boolean): Tether;
20

21
/**
22
 * Adds a one-time event listener that will be removed after first execution
23
 * @param event - Event name to listen for
24
 * @param handler - Function to call when event is triggered
25
 * @param ctx - Context (this value) for the handler function
26
 * @returns The tether instance for method chaining
27
 */
28
once(event: string, handler: Function, ctx?: any): Tether;
29
```
30

31
**Usage Examples:**
32

33
```javascript
34
import Tether from "tether";
35

36
const tether = new Tether({
37
  element: '.tooltip',
38
  target: '.button',
39
  attachment: 'top center',
40
  targetAttachment: 'bottom center'
41
});
42

43
// Listen for positioning updates
44
tether.on('update', function(data) {
45
  console.log('Attachment changed:', data.attachment, data.targetAttachment);
46
});
47

48
// Listen for repositioning events
49
tether.on('repositioned', function() {
50
  console.log('Element has been repositioned');
51
});
52

53
// One-time listener
54
tether.once('repositioned', function() {
55
  console.log('First reposition complete');
56
});
57

58
// Custom context
59
tether.on('update', function(data) {
60
  this.handleUpdate(data);
61
}, myObject);
62
```
63

64
### Event Removal
65

66
Remove event listeners from the tether instance.
67

68
```javascript { .api }
69
/**
70
 * Removes event listeners
71
 * @param event - Event name to remove listeners for (optional)
72
 * @param handler - Specific handler to remove (optional)
73
 * @returns The tether instance for method chaining
74
 */
75
off(event?: string, handler?: Function): Tether;
76
```
77

78
**Usage Examples:**
79

80
```javascript
81
// Remove all listeners for 'update' event
82
tether.off('update');
83

84
// Remove specific handler
85
const myHandler = function(data) { /* ... */ };
86
tether.on('update', myHandler);
87
tether.off('update', myHandler);
88

89
// Remove all event listeners
90
tether.off();
91
```
92

93
### Event Triggering
94

95
Manually trigger events on the tether instance.
96

97
```javascript { .api }
98
/**
99
 * Triggers an event on the tether instance
100
 * @param event - Event name to trigger
101
 * @param args - Arguments to pass to event handlers
102
 * @returns The tether instance for method chaining
103
 */
104
trigger(event: string, ...args: any[]): Tether;
105
```
106

107
**Usage Example:**
108

109
```javascript
110
// Manually trigger a custom event
111
tether.trigger('custom-event', { customData: 'value' });
112
```
113

114
## Built-in Events
115

116
### 'update' Event
117

118
Fired when attachment points change due to constraints or positioning adjustments.
119

120
```javascript { .api }
121
interface UpdateEventData {
122
  /** New element attachment configuration */
123
  attachment: AttachmentConfig;
124
  /** New target attachment configuration */
125
  targetAttachment: AttachmentConfig;
126
}
127
```
128

129
**Usage Example:**
130

131
```javascript
132
tether.on('update', function(data) {
133
  // Handle attachment point changes
134
  console.log('Element attachment:', data.attachment);
135
  console.log('Target attachment:', data.targetAttachment);
136
  
137
  // Update UI or perform custom logic
138
  if (data.attachment.top === 'bottom') {
139
    element.classList.add('flipped');
140
  }
141
});
142
```
143

144
### 'repositioned' Event
145

146
Fired after the element has been repositioned in the DOM.
147

148
**Usage Example:**
149

150
```javascript
151
tether.on('repositioned', function() {
152
  // Element position has been updated
153
  console.log('Element repositioned');
154
  
155
  // Trigger animations or other side effects
156
  element.classList.add('positioned');
157
  
158
  // Notify other components
159
  this.notifyPositionChange();
160
});
161
```
162

163
## Event Patterns
164

165
### Chaining Event Handlers
166

167
Events support method chaining for fluent API usage.
168

169
```javascript
170
tether
171
  .on('update', handleUpdate)
172
  .on('repositioned', handleReposition)
173
  .once('repositioned', handleFirstReposition)
174
  .enable();
175
```
176

177
### Error Handling in Events
178

179
Handle errors gracefully in event handlers.
180

181
```javascript
182
tether.on('update', function(data) {
183
  try {
184
    // Your event handling logic
185
    this.processUpdate(data);
186
  } catch (error) {
187
    console.error('Error handling update event:', error);
188
  }
189
});
190
```
191

192
### Context Management
193

194
Use context parameter to maintain proper `this` binding.
195

196
```javascript
197
class MyComponent {
198
  constructor() {
199
    this.tether = new Tether({
200
      element: '.my-element',
201
      target: '.my-target',
202
      attachment: 'top center',
203
      targetAttachment: 'bottom center'
204
    });
205
    
206
    // Bind events with component context
207
    this.tether.on('update', this.handleUpdate, this);
208
    this.tether.on('repositioned', this.handleReposition, this);
209
  }
210
  
211
  handleUpdate(data) {
212
    // 'this' refers to MyComponent instance
213
    this.updateState(data);
214
  }
215
  
216
  handleReposition() {
217
    // 'this' refers to MyComponent instance
218
    this.onPositionChange();
219
  }
220
}
221
```
222

223
## Types
224

225
```javascript { .api }
226
interface AttachmentConfig {
227
  top: string | false;
228
  left: string | false;
229
}
230

231
type EventHandler = (...args: any[]) => void;
232

233
interface EventBinding {
234
  handler: EventHandler;
235
  ctx: any;
236
  once: boolean;
237
}
238

239
interface EventedInstance {
240
  bindings?: {
241
    [eventName: string]: EventBinding[];
242
  };
243
}
244

245
// Built-in Tether events
246
type TetherEventName = 'update' | 'repositioned' | string;
247
```