index.d.ts (10757B)
1 export as namespace EventTargetShim 2 3 /** 4 * `Event` interface. 5 * @see https://dom.spec.whatwg.org/#event 6 */ 7 export interface Event { 8 /** 9 * The type of this event. 10 */ 11 readonly type: string 12 13 /** 14 * The target of this event. 15 */ 16 readonly target: EventTarget<{}, {}, "standard"> | null 17 18 /** 19 * The current target of this event. 20 */ 21 readonly currentTarget: EventTarget<{}, {}, "standard"> | null 22 23 /** 24 * The target of this event. 25 * @deprecated 26 */ 27 readonly srcElement: any | null 28 29 /** 30 * The composed path of this event. 31 */ 32 composedPath(): EventTarget<{}, {}, "standard">[] 33 34 /** 35 * Constant of NONE. 36 */ 37 readonly NONE: number 38 39 /** 40 * Constant of CAPTURING_PHASE. 41 */ 42 readonly CAPTURING_PHASE: number 43 44 /** 45 * Constant of BUBBLING_PHASE. 46 */ 47 readonly BUBBLING_PHASE: number 48 49 /** 50 * Constant of AT_TARGET. 51 */ 52 readonly AT_TARGET: number 53 54 /** 55 * Indicates which phase of the event flow is currently being evaluated. 56 */ 57 readonly eventPhase: number 58 59 /** 60 * Stop event bubbling. 61 */ 62 stopPropagation(): void 63 64 /** 65 * Stop event bubbling. 66 */ 67 stopImmediatePropagation(): void 68 69 /** 70 * Initialize event. 71 * @deprecated 72 */ 73 initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void 74 75 /** 76 * The flag indicating bubbling. 77 */ 78 readonly bubbles: boolean 79 80 /** 81 * Stop event bubbling. 82 * @deprecated 83 */ 84 cancelBubble: boolean 85 86 /** 87 * Set or get cancellation flag. 88 * @deprecated 89 */ 90 returnValue: boolean 91 92 /** 93 * The flag indicating whether the event can be canceled. 94 */ 95 readonly cancelable: boolean 96 97 /** 98 * Cancel this event. 99 */ 100 preventDefault(): void 101 102 /** 103 * The flag to indicating whether the event was canceled. 104 */ 105 readonly defaultPrevented: boolean 106 107 /** 108 * The flag to indicating if event is composed. 109 */ 110 readonly composed: boolean 111 112 /** 113 * Indicates whether the event was dispatched by the user agent. 114 */ 115 readonly isTrusted: boolean 116 117 /** 118 * The unix time of this event. 119 */ 120 readonly timeStamp: number 121 } 122 123 /** 124 * The constructor of `EventTarget` interface. 125 */ 126 export type EventTargetConstructor< 127 TEvents extends EventTarget.EventDefinition = {}, 128 TEventAttributes extends EventTarget.EventDefinition = {}, 129 TMode extends EventTarget.Mode = "loose" 130 > = { 131 prototype: EventTarget<TEvents, TEventAttributes, TMode> 132 new(): EventTarget<TEvents, TEventAttributes, TMode> 133 } 134 135 /** 136 * `EventTarget` interface. 137 * @see https://dom.spec.whatwg.org/#interface-eventtarget 138 */ 139 export type EventTarget< 140 TEvents extends EventTarget.EventDefinition = {}, 141 TEventAttributes extends EventTarget.EventDefinition = {}, 142 TMode extends EventTarget.Mode = "loose" 143 > = EventTarget.EventAttributes<TEventAttributes> & { 144 /** 145 * Add a given listener to this event target. 146 * @param eventName The event name to add. 147 * @param listener The listener to add. 148 * @param options The options for this listener. 149 */ 150 addEventListener<TEventType extends EventTarget.EventType<TEvents, TMode>>( 151 type: TEventType, 152 listener: 153 | EventTarget.Listener<EventTarget.PickEvent<TEvents, TEventType>> 154 | null, 155 options?: boolean | EventTarget.AddOptions 156 ): void 157 158 /** 159 * Remove a given listener from this event target. 160 * @param eventName The event name to remove. 161 * @param listener The listener to remove. 162 * @param options The options for this listener. 163 */ 164 removeEventListener<TEventType extends EventTarget.EventType<TEvents, TMode>>( 165 type: TEventType, 166 listener: 167 | EventTarget.Listener<EventTarget.PickEvent<TEvents, TEventType>> 168 | null, 169 options?: boolean | EventTarget.RemoveOptions 170 ): void 171 172 /** 173 * Dispatch a given event. 174 * @param event The event to dispatch. 175 * @returns `false` if canceled. 176 */ 177 dispatchEvent<TEventType extends EventTarget.EventType<TEvents, TMode>>( 178 event: EventTarget.EventData<TEvents, TEventType, TMode> 179 ): boolean 180 } 181 182 export const EventTarget: EventTargetConstructor & { 183 /** 184 * Create an `EventTarget` instance with detailed event definition. 185 * 186 * The detailed event definition requires to use `defineEventAttribute()` 187 * function later. 188 * 189 * Unfortunately, the second type parameter `TEventAttributes` was needed 190 * because we cannot compute string literal types. 191 * 192 * @example 193 * const signal = new EventTarget<{ abort: Event }, { onabort: Event }>() 194 * defineEventAttribute(signal, "abort") 195 */ 196 new < 197 TEvents extends EventTarget.EventDefinition, 198 TEventAttributes extends EventTarget.EventDefinition, 199 TMode extends EventTarget.Mode = "loose" 200 >(): EventTarget<TEvents, TEventAttributes, TMode> 201 202 /** 203 * Define an `EventTarget` constructor with attribute events and detailed event definition. 204 * 205 * Unfortunately, the second type parameter `TEventAttributes` was needed 206 * because we cannot compute string literal types. 207 * 208 * @example 209 * class AbortSignal extends EventTarget<{ abort: Event }, { onabort: Event }>("abort") { 210 * abort(): void {} 211 * } 212 * 213 * @param events Optional event attributes (e.g. passing in `"click"` adds `onclick` to prototype). 214 */ 215 < 216 TEvents extends EventTarget.EventDefinition = {}, 217 TEventAttributes extends EventTarget.EventDefinition = {}, 218 TMode extends EventTarget.Mode = "loose" 219 >(events: string[]): EventTargetConstructor< 220 TEvents, 221 TEventAttributes, 222 TMode 223 > 224 225 /** 226 * Define an `EventTarget` constructor with attribute events and detailed event definition. 227 * 228 * Unfortunately, the second type parameter `TEventAttributes` was needed 229 * because we cannot compute string literal types. 230 * 231 * @example 232 * class AbortSignal extends EventTarget<{ abort: Event }, { onabort: Event }>("abort") { 233 * abort(): void {} 234 * } 235 * 236 * @param events Optional event attributes (e.g. passing in `"click"` adds `onclick` to prototype). 237 */ 238 < 239 TEvents extends EventTarget.EventDefinition = {}, 240 TEventAttributes extends EventTarget.EventDefinition = {}, 241 TMode extends EventTarget.Mode = "loose" 242 >(event0: string, ...events: string[]): EventTargetConstructor< 243 TEvents, 244 TEventAttributes, 245 TMode 246 > 247 } 248 249 export namespace EventTarget { 250 /** 251 * Options of `removeEventListener()` method. 252 */ 253 export interface RemoveOptions { 254 /** 255 * The flag to indicate that the listener is for the capturing phase. 256 */ 257 capture?: boolean 258 } 259 260 /** 261 * Options of `addEventListener()` method. 262 */ 263 export interface AddOptions extends RemoveOptions { 264 /** 265 * The flag to indicate that the listener doesn't support 266 * `event.preventDefault()` operation. 267 */ 268 passive?: boolean 269 /** 270 * The flag to indicate that the listener will be removed on the first 271 * event. 272 */ 273 once?: boolean 274 } 275 276 /** 277 * The type of regular listeners. 278 */ 279 export interface FunctionListener<TEvent> { 280 (event: TEvent): void 281 } 282 283 /** 284 * The type of object listeners. 285 */ 286 export interface ObjectListener<TEvent> { 287 handleEvent(event: TEvent): void 288 } 289 290 /** 291 * The type of listeners. 292 */ 293 export type Listener<TEvent> = 294 | FunctionListener<TEvent> 295 | ObjectListener<TEvent> 296 297 /** 298 * Event definition. 299 */ 300 export type EventDefinition = { 301 readonly [key: string]: Event 302 } 303 304 /** 305 * Mapped type for event attributes. 306 */ 307 export type EventAttributes<TEventAttributes extends EventDefinition> = { 308 [P in keyof TEventAttributes]: 309 | FunctionListener<TEventAttributes[P]> 310 | null 311 } 312 313 /** 314 * The type of event data for `dispatchEvent()` method. 315 */ 316 export type EventData< 317 TEvents extends EventDefinition, 318 TEventType extends keyof TEvents | string, 319 TMode extends Mode 320 > = 321 TEventType extends keyof TEvents 322 ? ( 323 // Require properties which are not generated automatically. 324 & Pick< 325 TEvents[TEventType], 326 Exclude<keyof TEvents[TEventType], OmittableEventKeys> 327 > 328 // Properties which are generated automatically are optional. 329 & Partial<Pick<Event, OmittableEventKeys>> 330 ) 331 : ( 332 TMode extends "standard" 333 ? Event 334 : Event | NonStandardEvent 335 ) 336 337 /** 338 * The string literal types of the properties which are generated 339 * automatically in `dispatchEvent()` method. 340 */ 341 export type OmittableEventKeys = Exclude<keyof Event, "type"> 342 343 /** 344 * The type of event data. 345 */ 346 export type NonStandardEvent = { 347 [key: string]: any 348 type: string 349 } 350 351 /** 352 * The type of listeners. 353 */ 354 export type PickEvent< 355 TEvents extends EventDefinition, 356 TEventType extends keyof TEvents | string, 357 > = 358 TEventType extends keyof TEvents 359 ? TEvents[TEventType] 360 : Event 361 362 /** 363 * Event type candidates. 364 */ 365 export type EventType< 366 TEvents extends EventDefinition, 367 TMode extends Mode 368 > = 369 TMode extends "strict" 370 ? keyof TEvents 371 : keyof TEvents | string 372 373 /** 374 * - `"strict"` ..... Methods don't accept unknown events. 375 * `dispatchEvent()` accepts partial objects. 376 * - `"loose"` ...... Methods accept unknown events. 377 * `dispatchEvent()` accepts partial objects. 378 * - `"standard"` ... Methods accept unknown events. 379 * `dispatchEvent()` doesn't accept partial objects. 380 */ 381 export type Mode = "strict" | "standard" | "loose" 382 } 383 384 /** 385 * Specialized `type` property. 386 */ 387 export type Type<T extends string> = { type: T } 388 389 /** 390 * Define an event attribute (e.g. `eventTarget.onclick`). 391 * @param prototype The event target prototype to define an event attribute. 392 * @param eventName The event name to define. 393 */ 394 export function defineEventAttribute( 395 prototype: EventTarget, 396 eventName: string 397 ): void 398 399 export default EventTarget