index.d.ts 11 KB

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