event_dispatcher.d-K56StcHr.d.ts 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395
  1. /**
  2. * @license Angular v19.2.13
  3. * (c) 2010-2025 Google LLC. https://angular.io/
  4. * License: MIT
  5. */
  6. declare global {
  7. /**
  8. * Values of ngDevMode
  9. * Depending on the current state of the application, ngDevMode may have one of several values.
  10. *
  11. * For convenience, the “truthy” value which enables dev mode is also an object which contains
  12. * Angular’s performance counters. This is not necessary, but cuts down on boilerplate for the
  13. * perf counters.
  14. *
  15. * ngDevMode may also be set to false. This can happen in one of a few ways:
  16. * - The user explicitly sets `window.ngDevMode = false` somewhere in their app.
  17. * - The user calls `enableProdMode()`.
  18. * - The URL contains a `ngDevMode=false` text.
  19. * Finally, ngDevMode may not have been defined at all.
  20. */
  21. const ngDevMode: null | NgDevModePerfCounters;
  22. interface NgDevModePerfCounters {
  23. namedConstructors: boolean;
  24. firstCreatePass: number;
  25. tNode: number;
  26. tView: number;
  27. rendererCreateTextNode: number;
  28. rendererSetText: number;
  29. rendererCreateElement: number;
  30. rendererAddEventListener: number;
  31. rendererSetAttribute: number;
  32. rendererRemoveAttribute: number;
  33. rendererSetProperty: number;
  34. rendererSetClassName: number;
  35. rendererAddClass: number;
  36. rendererRemoveClass: number;
  37. rendererSetStyle: number;
  38. rendererRemoveStyle: number;
  39. rendererDestroy: number;
  40. rendererDestroyNode: number;
  41. rendererMoveNode: number;
  42. rendererRemoveNode: number;
  43. rendererAppendChild: number;
  44. rendererInsertBefore: number;
  45. rendererCreateComment: number;
  46. hydratedNodes: number;
  47. hydratedComponents: number;
  48. dehydratedViewsRemoved: number;
  49. dehydratedViewsCleanupRuns: number;
  50. componentsSkippedHydration: number;
  51. deferBlocksWithIncrementalHydration: number;
  52. }
  53. }
  54. /**
  55. * Records information about the action that should handle a given `Event`.
  56. */
  57. interface ActionInfo {
  58. name: string;
  59. element: Element;
  60. }
  61. type ActionInfoInternal = [name: string, element: Element];
  62. /**
  63. * Records information for later handling of events. This type is
  64. * shared, and instances of it are passed, between the eventcontract
  65. * and the dispatcher jsbinary. Therefore, the fields of this type are
  66. * referenced by string literals rather than property literals
  67. * throughout the code.
  68. *
  69. * 'targetElement' is the element the action occurred on, 'actionElement'
  70. * is the element that has the jsaction handler.
  71. *
  72. * A null 'actionElement' identifies an EventInfo instance that didn't match a
  73. * jsaction attribute. This allows us to execute global event handlers with the
  74. * appropriate event type (including a11y clicks and custom events).
  75. * The declare portion of this interface creates a set of externs that make sure
  76. * renaming doesn't happen for EventInfo. This is important since EventInfo
  77. * is shared across multiple binaries.
  78. */
  79. declare interface EventInfo {
  80. eventType: string;
  81. event: Event;
  82. targetElement: Element;
  83. /** The element that is the container for this Event. */
  84. eic: Element;
  85. timeStamp: number;
  86. /**
  87. * The action parsed from the JSAction element.
  88. */
  89. eia?: ActionInfoInternal;
  90. /**
  91. * Whether this `Event` is a replay event, meaning no dispatcher was
  92. * installed when this `Event` was originally dispatched.
  93. */
  94. eirp?: boolean;
  95. /**
  96. * Whether this `Event` represents a `keydown` event that should be processed
  97. * as a `click`. Only used when a11y click events is on.
  98. */
  99. eiack?: boolean;
  100. /** Whether action resolution has already run on this `EventInfo`. */
  101. eir?: boolean;
  102. }
  103. /**
  104. * Utility class around an `EventInfo`.
  105. *
  106. * This should be used in compilation units that are less sensitive to code
  107. * size.
  108. */
  109. declare class EventInfoWrapper {
  110. readonly eventInfo: EventInfo;
  111. constructor(eventInfo: EventInfo);
  112. getEventType(): string;
  113. setEventType(eventType: string): void;
  114. getEvent(): Event;
  115. setEvent(event: Event): void;
  116. getTargetElement(): Element;
  117. setTargetElement(targetElement: Element): void;
  118. getContainer(): Element;
  119. setContainer(container: Element): void;
  120. getTimestamp(): number;
  121. setTimestamp(timestamp: number): void;
  122. getAction(): {
  123. name: string;
  124. element: Element;
  125. } | undefined;
  126. setAction(action: ActionInfo | undefined): void;
  127. getIsReplay(): boolean | undefined;
  128. setIsReplay(replay: boolean): void;
  129. getResolved(): boolean | undefined;
  130. setResolved(resolved: boolean): void;
  131. clone(): EventInfoWrapper;
  132. }
  133. declare interface EarlyJsactionDataContainer {
  134. _ejsa?: EarlyJsactionData;
  135. _ejsas?: {
  136. [appId: string]: EarlyJsactionData | undefined;
  137. };
  138. }
  139. declare global {
  140. interface Window {
  141. _ejsa?: EarlyJsactionData;
  142. _ejsas?: {
  143. [appId: string]: EarlyJsactionData | undefined;
  144. };
  145. }
  146. }
  147. /**
  148. * Defines the early jsaction data types.
  149. */
  150. declare interface EarlyJsactionData {
  151. /** List used to keep track of the early JSAction event types. */
  152. et: string[];
  153. /** List used to keep track of the early JSAction capture event types. */
  154. etc: string[];
  155. /** Early JSAction handler for all events. */
  156. h: (event: Event) => void;
  157. /** Dispatcher handler. Initializes to populating `q`. */
  158. d: (eventInfo: EventInfo) => void;
  159. /** List used to push `EventInfo` objects if the dispatcher is not registered. */
  160. q: EventInfo[];
  161. /** Container for listening to events. */
  162. c: HTMLElement;
  163. }
  164. /**
  165. * An `EventContractContainerManager` provides the common interface for managing
  166. * containers.
  167. */
  168. interface EventContractContainerManager {
  169. addEventListener(eventType: string, getHandler: (element: Element) => (event: Event) => void, passive?: boolean): void;
  170. cleanUp(): void;
  171. }
  172. /**
  173. * A class representing a container node and all the event handlers
  174. * installed on it. Used so that handlers can be cleaned up if the
  175. * container is removed from the contract.
  176. */
  177. declare class EventContractContainer implements EventContractContainerManager {
  178. readonly element: Element;
  179. /**
  180. * Array of event handlers and their corresponding event types that are
  181. * installed on this container.
  182. *
  183. */
  184. private handlerInfos;
  185. /**
  186. * @param element The container Element.
  187. */
  188. constructor(element: Element);
  189. /**
  190. * Installs the provided installer on the element owned by this container,
  191. * and maintains a reference to resulting handler in order to remove it
  192. * later if desired.
  193. */
  194. addEventListener(eventType: string, getHandler: (element: Element) => (event: Event) => void, passive?: boolean): void;
  195. /**
  196. * Removes all the handlers installed on this container.
  197. */
  198. cleanUp(): void;
  199. }
  200. /**
  201. * @fileoverview An enum to control who can call certain jsaction APIs.
  202. */
  203. declare enum Restriction {
  204. I_AM_THE_JSACTION_FRAMEWORK = 0
  205. }
  206. /**
  207. * @fileoverview Implements the local event handling contract. This
  208. * allows DOM objects in a container that enters into this contract to
  209. * define event handlers which are executed in a local context.
  210. *
  211. * One EventContract instance can manage the contract for multiple
  212. * containers, which are added using the addContainer() method.
  213. *
  214. * Events can be registered using the addEvent() method.
  215. *
  216. * A Dispatcher is added using the registerDispatcher() method. Until there is
  217. * a dispatcher, events are queued. The idea is that the EventContract
  218. * class is inlined in the HTML of the top level page and instantiated
  219. * right after the start of <body>. The Dispatcher class is contained
  220. * in the external deferred js, and instantiated and registered with
  221. * EventContract when the external javascript in the page loads. The
  222. * external javascript will also register the jsaction handlers, which
  223. * then pick up the queued events at the time of registration.
  224. *
  225. * Since this class is meant to be inlined in the main page HTML, the
  226. * size of the binary compiled from this file MUST be kept as small as
  227. * possible and thus its dependencies to a minimum.
  228. */
  229. /**
  230. * The API of an EventContract that is safe to call from any compilation unit.
  231. */
  232. declare interface UnrenamedEventContract {
  233. ecrd(dispatcher: Dispatcher, restriction: Restriction): void;
  234. }
  235. /** A function that is called to handle events captured by the EventContract. */
  236. type Dispatcher = (eventInfo: EventInfo, globalDispatch?: boolean) => void;
  237. /**
  238. * A function that handles an event dispatched from the browser.
  239. *
  240. * eventType: May differ from `event.type` if JSAction uses a
  241. * short-hand name or is patching over an non-bubbling event with a bubbling
  242. * variant.
  243. * event: The native browser event.
  244. * container: The container for this dispatch.
  245. */
  246. type EventHandler = (eventType: string, event: Event, container: Element) => void;
  247. /**
  248. * EventContract intercepts events in the bubbling phase at the
  249. * boundary of a container element, and maps them to generic actions
  250. * which are specified using the custom jsaction attribute in
  251. * HTML. Behavior of the application is then specified in terms of
  252. * handler for such actions, cf. jsaction.Dispatcher in dispatcher.js.
  253. *
  254. * This has several benefits: (1) No DOM event handlers need to be
  255. * registered on the specific elements in the UI. (2) The set of
  256. * events that the application has to handle can be specified in terms
  257. * of the semantics of the application, rather than in terms of DOM
  258. * events. (3) Invocation of handlers can be delayed and handlers can
  259. * be delay loaded in a generic way.
  260. */
  261. declare class EventContract implements UnrenamedEventContract {
  262. static MOUSE_SPECIAL_SUPPORT: boolean;
  263. private containerManager;
  264. /**
  265. * The DOM events which this contract covers. Used to prevent double
  266. * registration of event types. The value of the map is the
  267. * internally created DOM event handler function that handles the
  268. * DOM events. See addEvent().
  269. *
  270. */
  271. private eventHandlers;
  272. private browserEventTypeToExtraEventTypes;
  273. /**
  274. * The dispatcher function. Events are passed to this function for
  275. * handling once it was set using the registerDispatcher() method. This is
  276. * done because the function is passed from another jsbinary, so passing the
  277. * instance and invoking the method here would require to leave the method
  278. * unobfuscated.
  279. */
  280. private dispatcher;
  281. /**
  282. * The list of suspended `EventInfo` that will be dispatched
  283. * as soon as the `Dispatcher` is registered.
  284. */
  285. private queuedEventInfos;
  286. constructor(containerManager: EventContractContainerManager);
  287. private handleEvent;
  288. /**
  289. * Handle an `EventInfo`.
  290. */
  291. private handleEventInfo;
  292. /**
  293. * Enables jsaction handlers to be called for the event type given by
  294. * name.
  295. *
  296. * If the event is already registered, this does nothing.
  297. *
  298. * @param prefixedEventType If supplied, this event is used in
  299. * the actual browser event registration instead of the name that is
  300. * exposed to jsaction. Use this if you e.g. want users to be able
  301. * to subscribe to jsaction="transitionEnd:foo" while the underlying
  302. * event is webkitTransitionEnd in one browser and mozTransitionEnd
  303. * in another.
  304. *
  305. * @param passive A boolean value that, if `true`, indicates that the event
  306. * handler will never call `preventDefault()`.
  307. */
  308. addEvent(eventType: string, prefixedEventType?: string, passive?: boolean): void;
  309. /**
  310. * Gets the queued early events and replay them using the appropriate handler
  311. * in the provided event contract. Once all the events are replayed, it cleans
  312. * up the early contract.
  313. */
  314. replayEarlyEvents(earlyJsactionData?: EarlyJsactionData | undefined): void;
  315. /**
  316. * Replays all the early `EventInfo` objects, dispatching them through the normal
  317. * `EventContract` flow.
  318. */
  319. replayEarlyEventInfos(earlyEventInfos: EventInfo[]): void;
  320. /**
  321. * Returns all JSAction event types that have been registered for a given
  322. * browser event type.
  323. */
  324. private getEventTypesForBrowserEventType;
  325. /**
  326. * Returns the event handler function for a given event type.
  327. */
  328. handler(eventType: string): EventHandler | undefined;
  329. /**
  330. * Cleans up the event contract. This resets all of the `EventContract`'s
  331. * internal state. Users are responsible for not using this `EventContract`
  332. * after it has been cleaned up.
  333. */
  334. cleanUp(): void;
  335. /**
  336. * Register a dispatcher function. Event info of each event mapped to
  337. * a jsaction is passed for handling to this callback. The queued
  338. * events are passed as well to the dispatcher for later replaying
  339. * once the dispatcher is registered. Clears the event queue to null.
  340. *
  341. * @param dispatcher The dispatcher function.
  342. * @param restriction
  343. */
  344. registerDispatcher(dispatcher: Dispatcher, restriction: Restriction): void;
  345. /**
  346. * Unrenamed alias for registerDispatcher. Necessary for any codebases that
  347. * split the `EventContract` and `Dispatcher` code into different compilation
  348. * units.
  349. */
  350. ecrd(dispatcher: Dispatcher, restriction: Restriction): void;
  351. }
  352. /** An internal symbol used to indicate whether propagation should be stopped or not. */
  353. declare const PROPAGATION_STOPPED_SYMBOL: unique symbol;
  354. /** Extra event phases beyond what the browser provides. */
  355. declare const EventPhase: {
  356. REPLAY: number;
  357. };
  358. declare global {
  359. interface Event {
  360. [PROPAGATION_STOPPED_SYMBOL]?: boolean;
  361. }
  362. }
  363. /**
  364. * A dispatcher that uses browser-based `Event` semantics, for example bubbling, `stopPropagation`,
  365. * `currentTarget`, etc.
  366. */
  367. declare class EventDispatcher {
  368. private readonly dispatchDelegate;
  369. private readonly clickModSupport;
  370. private readonly actionResolver;
  371. private readonly dispatcher;
  372. constructor(dispatchDelegate: (event: Event, actionName: string) => void, clickModSupport?: boolean);
  373. /**
  374. * The entrypoint for the `EventContract` dispatch.
  375. */
  376. dispatch(eventInfo: EventInfo): void;
  377. /** Internal method that does basic disaptching. */
  378. private dispatchToDelegate;
  379. }
  380. /**
  381. * Registers deferred functionality for an EventContract and a Jsaction
  382. * Dispatcher.
  383. */
  384. declare function registerDispatcher(eventContract: UnrenamedEventContract, dispatcher: EventDispatcher): void;
  385. export { EventContract, EventContractContainer, EventDispatcher, EventInfoWrapper, EventPhase, Restriction, registerDispatcher };
  386. export type { EarlyJsactionDataContainer, EventInfo };