UNPKG

26 kBTypeScriptView Raw
1// Type definitions for Mithril 2.0
2// Project: https://mithril.js.org/, https://github.com/mithriljs/mithril.js
3// Definitions by: Mike Linkovich <https://github.com/spacejack>
4// Claudia Meadows <https://github.com/dead-claudia>
5// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
6// TypeScript Version: 3.2
7
8/** Renders a vnode structure into a DOM element. */
9declare function render(el: Element, vnodes: Mithril.Children): void;
10
11/** Mounts a component to a DOM element, enabling it to autoredraw on user events. */
12declare function mount(element: Element, component: Mithril.ComponentTypes<any, any>): void;
13/** Unmounts a component from a DOM element. */
14declare function mount(element: Element, component: null): void; // tslint:disable-line unified-signatures
15
16/** Makes an XHR request and returns a promise. */
17declare function request<T>(options: Mithril.RequestOptions<T> & { url: string }): Promise<T>;
18/** Makes an XHR request and returns a promise. */
19declare function request<T>(url: string, options?: Mithril.RequestOptions<T>): Promise<T>;
20
21/** Makes a JSON-P request and returns a promise. */
22declare function jsonp<T>(options: Mithril.JsonpOptions & { url: string }): Promise<T>; // eslint-disable-line no-unnecessary-generics
23/** Makes a JSON-P request and returns a promise. */
24declare function jsonp<T>(url: string, options?: Mithril.JsonpOptions): Promise<T>; // eslint-disable-line no-unnecessary-generics
25
26declare namespace Mithril {
27 interface CommonAttributes<Attrs, State> {
28 /** The oninit hook is called before a vnode is touched by the virtual DOM engine. */
29 oninit?(this: State, vnode: Vnode<Attrs, State>): any;
30 /** The oncreate hook is called after a DOM element is created and attached to the document. */
31 oncreate?(this: State, vnode: VnodeDOM<Attrs, State>): any;
32 /** The onbeforeremove hook is called before a DOM element is detached from the document. If a Promise is returned, Mithril only detaches the DOM element after the promise completes. */
33 onbeforeremove?(this: State, vnode: VnodeDOM<Attrs, State>): Promise<any> | void;
34 /** The onremove hook is called before a DOM element is removed from the document. */
35 onremove?(this: State, vnode: VnodeDOM<Attrs, State>): any;
36 /** The onbeforeupdate hook is called before a vnode is diffed in a update. */
37 onbeforeupdate?(this: State, vnode: Vnode<Attrs, State>, old: VnodeDOM<Attrs, State>): boolean | void;
38 /** The onupdate hook is called after a DOM element is updated, while attached to the document. */
39 onupdate?(this: State, vnode: VnodeDOM<Attrs, State>): any;
40 /** A key to optionally associate with this element. */
41 key?: string | number | undefined;
42 }
43
44 interface Hyperscript {
45 /** Creates a virtual element (Vnode). */
46 <Attrs, State>(
47 component: ComponentTypes<Attrs, State>,
48 attributes: Attrs & CommonAttributes<Attrs, State>,
49 ...args: Children[]
50 ): Vnode<Attrs, State>;
51 /** Creates a virtual element (Vnode). */
52 (selector: string, attributes: Attributes, ...children: Children[]): Vnode<any, any>;
53 /** Creates a virtual element (Vnode). */
54 <Attrs, State>(component: ComponentTypes<Attrs, State>, ...args: Children[]): Vnode<Attrs, State>;
55 /** Creates a virtual element (Vnode). */
56 (selector: string, ...children: Children[]): Vnode<any, any>;
57 /** Creates a fragment virtual element (Vnode). */
58 fragment(attrs: CommonAttributes<any, any> & { [key: string]: any }, children: ChildArrayOrPrimitive): Vnode<any, any>;
59 /** Turns an HTML string into a virtual element (Vnode). Do not use trust on unsanitized user input. */
60 trust(html: string): Vnode<any, any>;
61 }
62
63 interface RouteResolver<Attrs = {}, State = {}> {
64 /** The onmatch hook is called when the router needs to find a component to render. */
65 onmatch?(
66 this: this,
67 args: Attrs,
68 requestedPath: string,
69 route: string,
70 ): ComponentTypes<any, any> | Promise<any> | void;
71 /** The render method is called on every redraw for a matching route. */
72 render?(this: this, vnode: Vnode<Attrs, State>): Children;
73 }
74
75 /** This represents a key-value mapping linking routes to components. */
76 interface RouteDefs {
77 /** The key represents the route. The value represents the corresponding component. */
78 [url: string]: ComponentTypes<any, any> | RouteResolver<any, any>;
79 }
80
81 interface RouteOptions {
82 /** Routing parameters. If path has routing parameter slots, the properties of this object are interpolated into the path string. */
83 replace?: boolean | undefined;
84 /** The state object to pass to the underlying history.pushState / history.replaceState call. */
85 state?: any;
86 /** The title string to pass to the underlying history.pushState / history.replaceState call. */
87 title?: string | undefined;
88 }
89
90 interface RouteLinkAttrs extends Attributes {
91 href: string;
92 selector?: string | ComponentTypes<any> | undefined;
93 options?: RouteOptions | undefined;
94 }
95
96 interface Route {
97 /** Creates application routes and mounts Components and/or RouteResolvers to a DOM element. */
98 (element: Element, defaultRoute: string, routes: RouteDefs): void;
99 /** Returns the last fully resolved routing path, without the prefix. */
100 get(): string;
101 /** Redirects to a matching route or to the default route if no matching routes can be found. */
102 set(route: string, data?: any, options?: RouteOptions): void;
103 /** Defines a router prefix which is a fragment of the URL that dictates the underlying strategy used by the router. */
104 prefix: string;
105 /** This Component renders a link <a href> that will use the current routing strategy */
106 Link: Component<RouteLinkAttrs>;
107 /** Returns the named parameter value from the current route. */
108 param(name: string): string;
109 /** Gets all route parameters. */
110 param(): any;
111 }
112
113 interface RequestOptions<T> {
114 /** The HTTP method to use. */
115 method?: string | undefined;
116 /** The data to be interpolated into the URL and serialized into the querystring. */
117 params?: { [key: string]: any } | undefined;
118 /** The data to be serialized into the request body. */
119 body?: (XMLHttpRequest['send'] extends (x: infer R) => any ? R : never) | (object & { [id: string]: any }) | undefined;
120 /** Whether the request should be asynchronous. Defaults to true. */
121 async?: boolean | undefined;
122 /** A username for HTTP authorization. */
123 user?: string | undefined;
124 /** A password for HTTP authorization. */
125 password?: string | undefined;
126 /** Whether to send cookies to 3rd party domains. */
127 withCredentials?: boolean | undefined;
128 /** Exposes the underlying XMLHttpRequest object for low-level configuration. */
129 config?(xhr: XMLHttpRequest, options: this): XMLHttpRequest | void;
130 /** Headers to append to the request before sending it. */
131 headers?: { [key: string]: string } | undefined;
132 /** A constructor to be applied to each object in the response. */
133 type?: new (o: any) => any;
134 /** A serialization method to be applied to data. Defaults to JSON.stringify, or if options.data is an instance of FormData, defaults to the identity function. */
135 serialize?(data: any): any;
136 /** A deserialization method to be applied to the response. Defaults to a small wrapper around JSON.parse that returns null for empty responses. */
137 deserialize?(data: string): T;
138 /** A hook to specify how the XMLHttpRequest response should be read. Useful for reading response headers and cookies. Defaults to a function that returns xhr.responseText */
139 extract?(xhr: XMLHttpRequest, options: this): T;
140 /**
141 * Force the use of the HTTP body section for data in GET requests when set to true,
142 * or the use of querystring for other HTTP methods when set to false.
143 * Defaults to false for GET requests and true for other methods.
144 */
145 useBody?: boolean | undefined;
146 /** If false, redraws mounted components upon completion of the request. If true, it does not. */
147 background?: boolean | undefined;
148 /** Milliseconds a request can take before automatically being terminated. */
149 timeout?: number | undefined;
150 /** The expected type of the response, as a legal value of XMLHttpRequest.responseType. */
151 responseType?: '' | 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | undefined;
152 }
153
154 interface JsonpOptions {
155 /** The data to be interpolated into the URL and serialized into the querystring. */
156 params?: { [id: string]: any } | undefined;
157 /** The data to be serialized into the request body. */
158 body?: any;
159 /** A constructor to be applied to each object in the response. */
160 type?: new (o: any) => any;
161 /** The name of the function that will be called as the callback. */
162 callbackName?: string | undefined;
163 /** The name of the querystring parameter name that specifies the callback name. */
164 callbackKey?: string | undefined;
165 /** If false, redraws mounted components upon completion of the request. If true, it does not. */
166 background?: boolean | undefined;
167 }
168
169 interface Redraw {
170 /** Manually triggers an asynchronous redraw of mounted components. */
171 (): void;
172 /** Manually triggers a synchronous redraw of mounted components. */
173 sync(): void;
174 }
175
176 type Params = object & ParamsRec;
177
178 interface ParamsRec {
179 // Ideally, it'd be this:
180 // `[key: string | number]: Params | !symbol & !object`
181 [key: string]: string | number | boolean | null | undefined | Params;
182 }
183
184 interface Static extends Hyperscript {
185 route: Route;
186 mount: typeof mount;
187 render: typeof render;
188 redraw: Redraw;
189 request: typeof request;
190 jsonp: typeof jsonp;
191 /** Returns an object with key/value pairs parsed from a string of the form: ?a=1&b=2 */
192 parseQueryString(queryString: string): Params;
193 /** Turns the key/value pairs of an object into a string of the form: a=1&b=2 */
194 buildQueryString(values: Params): string;
195 /** Parse path name */
196 parsePathname(url: string): { path: string; params: Params };
197 /** Build path name */
198 buildPathname(template: string, params?: Params): string;
199 }
200
201 // Vnode children types
202 type Child = Vnode<any, any> | string | number | boolean | null | undefined;
203 interface ChildArray extends Array<Children> {}
204 type Children = Child | ChildArray;
205 type ChildArrayOrPrimitive = ChildArray | string | number | boolean;
206
207 /** Virtual DOM nodes, or vnodes, are Javascript objects that represent an element (or parts of the DOM). */
208 interface Vnode<Attrs = {}, State = {}> {
209 /** The nodeName of a DOM element. It may also be the string [ if a vnode is a fragment, # if it's a text vnode, or < if it's a trusted HTML vnode. Additionally, it may be a component. */
210 tag: string | ComponentTypes<Attrs, State>;
211 /** A hashmap of DOM attributes, events, properties and lifecycle methods. */
212 attrs: Attrs;
213 /** An object that is persisted between redraws. In component vnodes, state is a shallow clone of the component object. */
214 state: State;
215 /** The value used to map a DOM element to its respective item in an array of data. */
216 key?: string | number | undefined;
217 /** In most vnode types, the children property is an array of vnodes. For text and trusted HTML vnodes, The children property is either a string, a number or a boolean. */
218 children?: ChildArrayOrPrimitive | undefined;
219 /**
220 * This is used instead of children if a vnode contains a text node as its only child.
221 * This is done for performance reasons.
222 * Component vnodes never use the text property even if they have a text node as their only child.
223 */
224 text?: string | number | boolean | undefined;
225 }
226
227 // In some lifecycle methods, Vnode will have a dom property
228 // and possibly a domSize property.
229 interface VnodeDOM<Attrs = {}, State = {}> extends Vnode<Attrs, State> {
230 /** Points to the element that corresponds to the vnode. */
231 dom: Element;
232 /** This defines the number of DOM elements that the vnode represents (starting from the element referenced by the dom property). */
233 domSize?: number | undefined;
234 }
235
236 type _NoLifecycle<T> = Omit<T, keyof Component>;
237
238 interface CVnode<A = {}> extends Vnode<A, ClassComponent<A>> {}
239
240 interface CVnodeDOM<A = {}> extends VnodeDOM<A, ClassComponent<A>> {}
241
242 /**
243 * Components are a mechanism to encapsulate parts of a view to make code easier to organize and/or reuse.
244 * Any Javascript object that has a view method can be used as a Mithril component.
245 * Components can be consumed via the m() utility.
246 */
247 interface Component<Attrs = {}, State = {}> {
248 /** The oninit hook is called before a vnode is touched by the virtual DOM engine. */
249 oninit?(this: _NoLifecycle<this & State>, vnode: Vnode<Attrs, _NoLifecycle<this & State>>): any;
250 /** The oncreate hook is called after a DOM element is created and attached to the document. */
251 oncreate?(this: _NoLifecycle<this & State>, vnode: VnodeDOM<Attrs, _NoLifecycle<this & State>>): any;
252 /** The onbeforeremove hook is called before a DOM element is detached from the document. If a Promise is returned, Mithril only detaches the DOM element after the promise completes. */
253 onbeforeremove?(this: _NoLifecycle<this & State>, vnode: VnodeDOM<Attrs, _NoLifecycle<this & State>>): Promise<any> | void;
254 /** The onremove hook is called before a DOM element is removed from the document. */
255 onremove?(this: _NoLifecycle<this & State>, vnode: VnodeDOM<Attrs, _NoLifecycle<this & State>>): any;
256 /** The onbeforeupdate hook is called before a vnode is diffed in a update. */
257 onbeforeupdate?(this: _NoLifecycle<this & State>, vnode: Vnode<Attrs, _NoLifecycle<this & State>>, old: VnodeDOM<Attrs, _NoLifecycle<this & State>>): boolean | void;
258 /** The onupdate hook is called after a DOM element is updated, while attached to the document. */
259 onupdate?(this: _NoLifecycle<this & State>, vnode: VnodeDOM<Attrs, _NoLifecycle<this & State>>): any;
260 /** Creates a view out of virtual elements. */
261 view(this: _NoLifecycle<this & State>, vnode: Vnode<Attrs, _NoLifecycle<this & State>>): Children | null | void;
262 }
263
264 /**
265 * Components are a mechanism to encapsulate parts of a view to make code easier to organize and/or reuse.
266 * Any class that implements a view method can be used as a Mithril component.
267 * Components can be consumed via the m() utility.
268 */
269 interface ClassComponent<A = {}> {
270 /** The oninit hook is called before a vnode is touched by the virtual DOM engine. */
271 oninit?(vnode: Vnode<A, this>): any;
272 /** The oncreate hook is called after a DOM element is created and attached to the document. */
273 oncreate?(vnode: VnodeDOM<A, this>): any;
274 /** The onbeforeremove hook is called before a DOM element is detached from the document. If a Promise is returned, Mithril only detaches the DOM element after the promise completes. */
275 onbeforeremove?(vnode: VnodeDOM<A, this>): Promise<any> | void;
276 /** The onremove hook is called before a DOM element is removed from the document. */
277 onremove?(vnode: VnodeDOM<A, this>): any;
278 /** The onbeforeupdate hook is called before a vnode is diffed in a update. */
279 onbeforeupdate?(vnode: Vnode<A, this>, old: VnodeDOM<A, this>): boolean | void;
280 /** The onupdate hook is called after a DOM element is updated, while attached to the document. */
281 onupdate?(vnode: VnodeDOM<A, this>): any;
282 /** Creates a view out of virtual elements. */
283 view(vnode: Vnode<A, this>): Children | null | void;
284 }
285
286 /**
287 * Components are a mechanism to encapsulate parts of a view to make code easier to organize and/or reuse.
288 * Any function that returns an object with a view method can be used as a Mithril component.
289 * Components can be consumed via the m() utility.
290 */
291 type FactoryComponent<A = {}> = (vnode: Vnode<A>) => Component<A>;
292
293 /**
294 * Components are a mechanism to encapsulate parts of a view to make code easier to organize and/or reuse.
295 * Any function that returns an object with a view method can be used as a Mithril component.
296 * Components can be consumed via the m() utility.
297 */
298 type ClosureComponent<A = {}> = FactoryComponent<A>;
299
300 /**
301 * Components are a mechanism to encapsulate parts of a view to make code easier to organize and/or reuse.
302 * Any Javascript object that has a view method is a Mithril component. Components can be consumed via the m() utility.
303 */
304 type Comp<Attrs = {}, State = {}> = _NoLifecycle<State> & Component<Attrs, _NoLifecycle<State>>;
305
306 /** Components are a mechanism to encapsulate parts of a view to make code easier to organize and/or reuse. Components can be consumed via the m() utility. */
307 type ComponentTypes<A = {}, S = {}> =
308 | Component<A, S>
309 | { new (vnode: CVnode<A>): ClassComponent<A> }
310 | FactoryComponent<A>;
311
312 /** This represents the attributes available for configuring virtual elements, beyond the applicable DOM attributes. */
313 interface Attributes extends CommonAttributes<any, any> {
314 /** The class name(s) for this virtual element, as a space-separated list. */
315 className?: string | undefined;
316 /** The class name(s) for this virtual element, as a space-separated list. */
317 class?: string | undefined;
318 /** Any other virtual element properties, including attributes and event handlers. */
319 [property: string]: any;
320 }
321}
322
323declare global {
324 namespace JSX {
325 // tslint:disable-next-line:no-empty-interface
326 interface Element extends Mithril.Vnode {}
327
328 // tslint:disable-next-line:no-empty-interface
329 interface IntrinsicAttributes extends Mithril.Attributes {}
330 // tslint:disable-next-line:no-empty-interface
331 interface IntrinsicClassAttributes extends Mithril.Attributes {}
332
333 interface IntrinsicElements {
334 // HTML
335 a: Mithril.Attributes;
336 abbr: Mithril.Attributes;
337 address: Mithril.Attributes;
338 area: Mithril.Attributes;
339 article: Mithril.Attributes;
340 aside: Mithril.Attributes;
341 audio: Mithril.Attributes;
342 b: Mithril.Attributes;
343 base: Mithril.Attributes;
344 bdi: Mithril.Attributes;
345 bdo: Mithril.Attributes;
346 big: Mithril.Attributes;
347 blockquote: Mithril.Attributes;
348 body: Mithril.Attributes;
349 br: Mithril.Attributes;
350 button: Mithril.Attributes;
351 canvas: Mithril.Attributes;
352 caption: Mithril.Attributes;
353 cite: Mithril.Attributes;
354 code: Mithril.Attributes;
355 col: Mithril.Attributes;
356 colgroup: Mithril.Attributes;
357 data: Mithril.Attributes;
358 datalist: Mithril.Attributes;
359 dd: Mithril.Attributes;
360 del: Mithril.Attributes;
361 details: Mithril.Attributes;
362 dfn: Mithril.Attributes;
363 dialog: Mithril.Attributes;
364 div: Mithril.Attributes;
365 dl: Mithril.Attributes;
366 dt: Mithril.Attributes;
367 em: Mithril.Attributes;
368 embed: Mithril.Attributes;
369 fieldset: Mithril.Attributes;
370 figcaption: Mithril.Attributes;
371 figure: Mithril.Attributes;
372 footer: Mithril.Attributes;
373 form: Mithril.Attributes;
374 h1: Mithril.Attributes;
375 h2: Mithril.Attributes;
376 h3: Mithril.Attributes;
377 h4: Mithril.Attributes;
378 h5: Mithril.Attributes;
379 h6: Mithril.Attributes;
380 head: Mithril.Attributes;
381 header: Mithril.Attributes;
382 hgroup: Mithril.Attributes;
383 hr: Mithril.Attributes;
384 html: Mithril.Attributes;
385 i: Mithril.Attributes;
386 iframe: Mithril.Attributes;
387 img: Mithril.Attributes;
388 input: Mithril.Attributes;
389 ins: Mithril.Attributes;
390 kbd: Mithril.Attributes;
391 keygen: Mithril.Attributes;
392 label: Mithril.Attributes;
393 legend: Mithril.Attributes;
394 li: Mithril.Attributes;
395 link: Mithril.Attributes;
396 main: Mithril.Attributes;
397 map: Mithril.Attributes;
398 mark: Mithril.Attributes;
399 menu: Mithril.Attributes;
400 menuitem: Mithril.Attributes;
401 meta: Mithril.Attributes;
402 meter: Mithril.Attributes;
403 nav: Mithril.Attributes;
404 noindex: Mithril.Attributes;
405 noscript: Mithril.Attributes;
406 object: Mithril.Attributes;
407 ol: Mithril.Attributes;
408 optgroup: Mithril.Attributes;
409 option: Mithril.Attributes;
410 output: Mithril.Attributes;
411 p: Mithril.Attributes;
412 param: Mithril.Attributes;
413 picture: Mithril.Attributes;
414 pre: Mithril.Attributes;
415 progress: Mithril.Attributes;
416 q: Mithril.Attributes;
417 rp: Mithril.Attributes;
418 rt: Mithril.Attributes;
419 ruby: Mithril.Attributes;
420 s: Mithril.Attributes;
421 samp: Mithril.Attributes;
422 script: Mithril.Attributes;
423 section: Mithril.Attributes;
424 select: Mithril.Attributes;
425 small: Mithril.Attributes;
426 source: Mithril.Attributes;
427 span: Mithril.Attributes;
428 strong: Mithril.Attributes;
429 style: Mithril.Attributes;
430 sub: Mithril.Attributes;
431 summary: Mithril.Attributes;
432 sup: Mithril.Attributes;
433 table: Mithril.Attributes;
434 template: Mithril.Attributes;
435 tbody: Mithril.Attributes;
436 td: Mithril.Attributes;
437 textarea: Mithril.Attributes;
438 tfoot: Mithril.Attributes;
439 th: Mithril.Attributes;
440 thead: Mithril.Attributes;
441 time: Mithril.Attributes;
442 title: Mithril.Attributes;
443 tr: Mithril.Attributes;
444 track: Mithril.Attributes;
445 u: Mithril.Attributes;
446 ul: Mithril.Attributes;
447 var: Mithril.Attributes;
448 video: Mithril.Attributes;
449 wbr: Mithril.Attributes;
450 webview: Mithril.Attributes;
451
452 // SVG
453 svg: Mithril.Attributes;
454 animate: Mithril.Attributes;
455 animateMotion: Mithril.Attributes;
456 animateTransform: Mithril.Attributes;
457 circle: Mithril.Attributes;
458 clipPath: Mithril.Attributes;
459 defs: Mithril.Attributes;
460 desc: Mithril.Attributes;
461 ellipse: Mithril.Attributes;
462 feBlend: Mithril.Attributes;
463 feColorMatrix: Mithril.Attributes;
464 feComponentTransfer: Mithril.Attributes;
465 feComposite: Mithril.Attributes;
466 feConvolveMatrix: Mithril.Attributes;
467 feDiffuseLighting: Mithril.Attributes;
468 feDisplacementMap: Mithril.Attributes;
469 feDistantLight: Mithril.Attributes;
470 feDropShadow: Mithril.Attributes;
471 feFlood: Mithril.Attributes;
472 feFuncA: Mithril.Attributes;
473 feFuncB: Mithril.Attributes;
474 feFuncG: Mithril.Attributes;
475 feFuncR: Mithril.Attributes;
476 feGaussianBlur: Mithril.Attributes;
477 feImage: Mithril.Attributes;
478 feMerge: Mithril.Attributes;
479 feMergeNode: Mithril.Attributes;
480 feMorphology: Mithril.Attributes;
481 feOffset: Mithril.Attributes;
482 fePointLight: Mithril.Attributes;
483 feSpecularLighting: Mithril.Attributes;
484 feSpotLight: Mithril.Attributes;
485 feTile: Mithril.Attributes;
486 feTurbulence: Mithril.Attributes;
487 filter: Mithril.Attributes;
488 foreignObject: Mithril.Attributes;
489 g: Mithril.Attributes;
490 image: Mithril.Attributes;
491 line: Mithril.Attributes;
492 linearGradient: Mithril.Attributes;
493 marker: Mithril.Attributes;
494 mask: Mithril.Attributes;
495 metadata: Mithril.Attributes;
496 mpath: Mithril.Attributes;
497 path: Mithril.Attributes;
498 pattern: Mithril.Attributes;
499 polygon: Mithril.Attributes;
500 polyline: Mithril.Attributes;
501 radialGradient: Mithril.Attributes;
502 rect: Mithril.Attributes;
503 stop: Mithril.Attributes;
504 switch: Mithril.Attributes;
505 symbol: Mithril.Attributes;
506 text: Mithril.Attributes;
507 textPath: Mithril.Attributes;
508 tspan: Mithril.Attributes;
509 use: Mithril.Attributes;
510 view: Mithril.Attributes;
511
512 // Special Mithril types
513 '[': Mithril.Attributes;
514 }
515 }
516}
517
518declare const Mithril: Mithril.Static;
519export = Mithril;