Add TypeScript definition (#123)

sindresorhus · Mar 19, 2019 · 4011361 · 4011361
1 parent 08139e5
commit 4011361
Show file tree

Hide file tree

Showing 9 changed files with 227 additions and 6 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
 node_modules
 yarn.lock
+dist/screenfull.test-d.ts
diff --git a/dist/screenfull.d.ts b/dist/screenfull.d.ts
@@ -0,0 +1,86 @@
+export type RawEventNames = {
+	readonly requestFullscreen: string;
+	readonly exitFullscreen: string;
+	readonly fullscreenElement: string;
+	readonly fullscreenEnabled: string;
+	readonly fullscreenchange: string;
+	readonly fullscreenerror: string;
+};
+
+export type EventName = 'change' | 'error';
+
+export interface Screenfull {
+	/**
+	A boolean whether fullscreen is active.
+	*/
+	readonly isFullscreen: boolean;
+
+	/**
+	The element currently in fullscreen, otherwise `null`.
+	*/
+	readonly element: Element | null;
+
+	/**
+	A boolean whether you are allowed to enter fullscreen. If your page is inside an `<iframe>` you will need to add a `allowfullscreen` attribute (+ `webkitallowfullscreen` and `mozallowfullscreen`).
+	*/
+	readonly enabled: boolean;
+
+	/**
+	Exposes the raw properties (prefixed if needed) used internally.
+	*/
+	raw: RawEventNames;
+
+	/**
+	Make an element fullscreen.
+
+	If your page is inside an `<iframe>` you will need to add a `allowfullscreen` attribute (+ `webkitallowfullscreen` and `mozallowfullscreen`).
+
+	Keep in mind that the browser will only enter fullscreen when initiated by user events like click, touch, key.
+
+	@param element - Default is `<html>`. If called with another element than the currently active, it will switch to that if it's a decendant.
+	@returns Resolves after the element enters fullscreen.
+	*/
+	request(element?: Element): Promise<void>;
+
+	/**
+	Brings you out of fullscreen.
+
+	@returns Resolves after the element exits fullscreen.
+	*/
+	exit(): Promise<void>;
+
+	/**
+	Requests fullscreen if not active, otherwise exits.
+
+	@returns Resolves after the element enters/exits fullscreen.
+	*/
+	toggle(element?: Element): Promise<void>;
+
+	/**
+	Add a listener for when the browser switches in and out of fullscreen or when there is an error.
+	*/
+	on(name: EventName, handler: (event: Event) => void): void;
+
+	/**
+	Remove a previously registered event listener.
+	*/
+	off(name: EventName, handler: (event: Event) => void): void;
+
+	/**
+	Alias for `.on('change', function)`.
+	*/
+	onchange(handler: (event: Event) => void): void;
+
+	/**
+	Alias for `.on('error', function)`.
+	*/
+	onerror(handler: (event: Event) => void): void;
+}
+
+/**
+Simple wrapper for cross-browser usage of the JavaScript [Fullscreen API](https://developer.mozilla.org/en/DOM/Using_full-screen_mode), which lets you bring the page or any element into fullscreen. Smoothens out the browser implementation differences, so you don't have to.
+*/
+declare const screenfull: Screenfull | false;
+
+export default screenfull;
+export as namespace screenfull;
diff --git a/dist/screenfull.js b/dist/screenfull.js
@@ -1,6 +1,6 @@
 /*!
 * screenfull
-* v4.0.1 - 2019-02-18
+* v4.0.1 - 2019-03-18
 * (c) Sindre Sorhus; MIT License
 */
 (function () {
@@ -181,6 +181,7 @@
 
 	if (isCommonjs) {
 		module.exports = screenfull;
+		module.exports.default = screenfull;
 	} else {
 		window.screenfull = screenfull;
 	}

diff --git a/dist/screenfull.min.js b/dist/screenfull.min.js
diff --git a/gruntfile.js b/gruntfile.js
@@ -33,11 +33,20 @@ module.exports = grunt => {
 					'dist/screenfull.min.js': 'src/screenfull.js'
 				}
 			}
+		},
+		copy: {
+			dist: {
+				files: {
+					'dist/screenfull.d.ts': 'src/screenfull.d.ts',
+					'dist/screenfull.test-d.ts': 'src/screenfull.test-d.ts'
+				}
+			}
 		}
 	});
 
 	grunt.registerTask('default', [
 		'concat',
-		'uglify'
+		'uglify',
+		'copy'
 	]);
 };
diff --git a/package.json b/package.json
@@ -14,21 +14,26 @@
 	},
 	"main": "dist/screenfull.js",
 	"files": [
-		"dist/screenfull.js"
+		"dist/screenfull.js",
+		"dist/screenfull.d.ts"
 	],
+	"types": "dist/screenfull.d.ts",
 	"keywords": [
 		"browser",
 		"fullscreen"
 	],
 	"devDependencies": {
 		"grunt": "^1.0.1",
 		"grunt-contrib-concat": "^1.0.0",
+		"grunt-contrib-copy": "^1.0.0",
 		"grunt-contrib-uglify": "^4.0.0",
 		"load-grunt-tasks": "^4.0.0",
+		"tsd-check": "^0.5.0",
 		"xo": "^0.16.0"
 	},
 	"scripts": {
-		"test": "xo"
+		"pretest": "grunt",
+		"test": "xo && tsd-check"
 	},
 	"xo": {
 		"envs": [

diff --git a/src/screenfull.d.ts b/src/screenfull.d.ts
@@ -0,0 +1,86 @@
+export type RawEventNames = {
+	readonly requestFullscreen: string;
+	readonly exitFullscreen: string;
+	readonly fullscreenElement: string;
+	readonly fullscreenEnabled: string;
+	readonly fullscreenchange: string;
+	readonly fullscreenerror: string;
+};
+
+export type EventName = 'change' | 'error';
+
+export interface Screenfull {
+	/**
+	A boolean whether fullscreen is active.
+	*/
+	readonly isFullscreen: boolean;
+
+	/**
+	The element currently in fullscreen, otherwise `null`.
+	*/
+	readonly element: Element | null;
+
+	/**
+	A boolean whether you are allowed to enter fullscreen. If your page is inside an `<iframe>` you will need to add a `allowfullscreen` attribute (+ `webkitallowfullscreen` and `mozallowfullscreen`).
+	*/
+	readonly enabled: boolean;
+
+	/**
+	Exposes the raw properties (prefixed if needed) used internally.
+	*/
+	raw: RawEventNames;
+
+	/**
+	Make an element fullscreen.
+
+	If your page is inside an `<iframe>` you will need to add a `allowfullscreen` attribute (+ `webkitallowfullscreen` and `mozallowfullscreen`).
+
+	Keep in mind that the browser will only enter fullscreen when initiated by user events like click, touch, key.
+
+	@param element - Default is `<html>`. If called with another element than the currently active, it will switch to that if it's a decendant.
+	@returns Resolves after the element enters fullscreen.
+	*/
+	request(element?: Element): Promise<void>;
+
+	/**
+	Brings you out of fullscreen.
+
+	@returns Resolves after the element exits fullscreen.
+	*/
+	exit(): Promise<void>;
+
+	/**
+	Requests fullscreen if not active, otherwise exits.
+
+	@returns Resolves after the element enters/exits fullscreen.
+	*/
+	toggle(element?: Element): Promise<void>;
+
+	/**
+	Add a listener for when the browser switches in and out of fullscreen or when there is an error.
+	*/
+	on(name: EventName, handler: (event: Event) => void): void;
+
+	/**
+	Remove a previously registered event listener.
+	*/
+	off(name: EventName, handler: (event: Event) => void): void;
+
+	/**
+	Alias for `.on('change', function)`.
+	*/
+	onchange(handler: (event: Event) => void): void;
+
+	/**
+	Alias for `.on('error', function)`.
+	*/
+	onerror(handler: (event: Event) => void): void;
+}
+
+/**
+Simple wrapper for cross-browser usage of the JavaScript [Fullscreen API](https://developer.mozilla.org/en/DOM/Using_full-screen_mode), which lets you bring the page or any element into fullscreen. Smoothens out the browser implementation differences, so you don't have to.
+*/
+declare const screenfull: Screenfull | false;
+
+export default screenfull;
+export as namespace screenfull;
diff --git a/src/screenfull.js b/src/screenfull.js
@@ -176,6 +176,7 @@
 
 	if (isCommonjs) {
 		module.exports = screenfull;
+		module.exports.default = screenfull;
 	} else {
 		window.screenfull = screenfull;
 	}

diff --git a/src/screenfull.test-d.ts b/src/screenfull.test-d.ts
@@ -0,0 +1,32 @@
+import {expectType} from 'tsd-check';
+import screenfull from '../dist/screenfull';
+
+if (screenfull) {
+	expectType<boolean>(screenfull.enabled);
+	expectType<boolean>(screenfull.isFullscreen);
+	expectType<Element | null>(screenfull.element);
+
+	if (screenfull.enabled) {
+		const element: Element = document.getElementById('target')!;
+
+		expectType<Promise<void>>(screenfull.request());
+		expectType<Promise<void>>(screenfull.request(element));
+		expectType<Promise<void>>(screenfull.toggle());
+		expectType<Promise<void>>(screenfull.toggle(element));
+		expectType<Promise<void>>(screenfull.exit());
+
+		screenfull.on('change', event => expectType<Event>(event));
+		screenfull.on('error', event => expectType<Event>(event));
+		screenfull.off('change', event => expectType<Event>(event));
+		screenfull.off('error', event => expectType<Event>(event));
+		screenfull.onchange(event => expectType<Event>(event));
+		screenfull.onerror(event => expectType<Event>(event));
+
+		expectType<string>(screenfull.raw.requestFullscreen);
+		expectType<string>(screenfull.raw.exitFullscreen);
+		expectType<string>(screenfull.raw.fullscreenElement);
+		expectType<string>(screenfull.raw.fullscreenEnabled);
+		expectType<string>(screenfull.raw.fullscreenchange);
+		expectType<string>(screenfull.raw.fullscreenerror);
+	}
+}