feature/add-openDocumentPictureInPicture-function (#77)

Author: alessiofrittoli

README.md

@@ -0,0 +1,211 @@
+/**
+ * @jest-environment jsdom
+ */
+import {
+	isDocumentPictureInPictureSupported,
+	requiresDocumentPictureInPictureAPI,
+	openDocumentPictureInPicture,
+	type OpenDocumentPictureInPictureOptions,
+} from '@/browser-api/picture-in-picture'
+import { ErrorCode } from '@/errors'
+
+import { cloneStyleSheets as _cloneStyleSheets, type Styles } from '@/dom'
+
+
+jest.mock( '@/dom', () => ( {
+	cloneStyleSheets: jest.fn( async () => {
+		return [
+			document.createElement( 'style' )
+		]
+	} )
+} ) )
+
+
+const cloneStyleSheets = _cloneStyleSheets as (
+	jest.Mock<ReturnType<typeof _cloneStyleSheets>, Parameters<typeof _cloneStyleSheets>>
+)
+
+
+interface RequestWindowOptions extends Omit<OpenDocumentPictureInPictureOptions, 'sizes'| 'styles' | 'onQuit'>
+{
+	width: number
+	height: number
+}
+
+
+describe( 'Document Picture-in-Picture', () => {
+
+	let mockDocumentPiPWindow: {
+		width: number
+		height: number
+		disallowReturnToOpener?: boolean
+		preferInitialWindowPlacement?: boolean
+		addEventListener: jest.Mock<void, [ event: string, listener: ( event: Event ) => void ]>
+		document: {
+			head: HTMLHeadElement
+		}
+	}
+
+	let mockRequestWindow: jest.Mock<typeof mockDocumentPiPWindow, [ options: RequestWindowOptions ]>
+
+	let mockDocumentPictureInPicture: jest.Mock<{
+		requestWindow?: typeof mockRequestWindow
+	}>
+
+	beforeEach( () => {
+
+		mockDocumentPiPWindow = {
+			width: 0,
+			height: 0,
+			disallowReturnToOpener: undefined,
+			preferInitialWindowPlacement: undefined,
+			addEventListener: jest.fn( ( event, listener ) => {
+				listener( new Event( event ) )
+			} ),
+			document: {
+				head: document.createElement( 'head' )
+			}
+		}
+
+		mockRequestWindow = jest.fn( options => {
+			Object.entries( options ).map( ( [ key, value ] ) => {
+				// @ts-expect-error couldn't infer types
+				mockDocumentPiPWindow[ key as keyof typeof mockDocumentPiPWindow ] = value
+			} )				
+			return mockDocumentPiPWindow
+		} )
+
+		mockDocumentPictureInPicture = jest.fn( () => ( {
+			requestWindow: mockRequestWindow
+		} ) )
+
+		Object.defineProperty( window, 'documentPictureInPicture', {
+			configurable	: true,
+			get				: mockDocumentPictureInPicture,
+		} )
+
+	} )
+
+
+	afterEach( () => {
+		jest.clearAllMocks()
+		Object.defineProperty( window, 'documentPictureInPicture', {
+			configurable	: true,
+			get				: undefined,
+		} )
+	} )
+
+
+	describe( 'isDocumentPictureInPictureSupported', () => {
+		
+		it( 'returns true if Document Picture-in-Picture API is available', () => {
+
+			expect( isDocumentPictureInPictureSupported() ).toBe( true )
+
+		} )
+
+
+		it( 'returns false if Document Picture-in-Picture API is not available', () => {
+
+			mockDocumentPictureInPicture.mockReturnValue( {} )
+			expect( isDocumentPictureInPictureSupported() ).toBe( false )
+
+		} )
+
+	} )
+	
+	
+	describe( 'requiresDocumentPictureInPictureAPI', () => {
+		
+		it( 'throws an Exception if Document Picture-in-Picture is not supported', () => {
+
+			mockDocumentPictureInPicture.mockReturnValue( {} )
+			
+			expect( requiresDocumentPictureInPictureAPI )
+				.toThrow( expect.objectContaining( { code: ErrorCode.DOCUMENT_PIP_NOT_SUPPORTED } ) )
+
+		} )
+
+
+		it( 'doesn\'t throw any Exception if Document Picture-in-Picture is supported', () => {
+
+			expect( requiresDocumentPictureInPictureAPI ).not.toThrow()
+
+		} )
+
+	} )
+
+
+	describe( 'openDocumentPictureInPicture', () => {
+
+		it( 'returns the new browsing context inside the Document Picture-in-Picture window with default options', async () => {
+
+			const { window: pipWindow } = await openDocumentPictureInPicture()
+			
+			expect( pipWindow ).toBeDefined()
+			expect( pipWindow ).toBe( mockDocumentPiPWindow ) // this pass only because we mocked the return value of `requestWindow`
+			expect( mockRequestWindow )
+				.toHaveBeenCalledWith( {
+					width: 250,
+					height: 250,
+					disallowReturnToOpener: undefined,
+					preferInitialWindowPlacement: undefined,
+				} )
+
+		} )
+		
+		
+		it( 'opens the Document Picture-in-Picture window with the given options', async () => {
+
+			await openDocumentPictureInPicture( {
+				sizes: [ 200, 300 ],
+				disallowReturnToOpener: true,
+				preferInitialWindowPlacement: true,
+			} )
+
+			expect( mockRequestWindow )
+				.toHaveBeenCalledWith( {
+					width: 200,
+					height: 300,
+					disallowReturnToOpener: true,
+					preferInitialWindowPlacement: true,
+				} )
+
+		} )
+
+
+		it( 'clones the current document stylesheets', async () => {
+
+			await openDocumentPictureInPicture()
+
+			expect( cloneStyleSheets )
+				.toHaveBeenCalledWith( document.styleSheets )
+
+		} )
+
+
+		it( 'clones the given stylesheets', async () => {
+
+			const styles: Styles = { url: '/path-to-custom-style.css', fetch: true }
+
+			await openDocumentPictureInPicture( { styles } )
+
+			expect( cloneStyleSheets )
+				.toHaveBeenNthCalledWith( 2, styles )
+
+		} )
+
+
+		it( 'calls given onQuit callback on Document Picture-in-Picture pagehide event', async () => {
+
+			const onQuit = jest.fn()
+
+			await openDocumentPictureInPicture( { onQuit } )
+
+			expect( onQuit ).toHaveBeenCalled()
+
+		} )
+
+	} )
+
+} )

__tests__/browser-api/picture-in-picture.test.ts

@@ -122,6 +122,7 @@
 	},
 	"dependencies": {
 		"@alessiofrittoli/date-utils": "^4.1.0",
+		"@alessiofrittoli/exception": "^3.5.0",
 		"@alessiofrittoli/fetcher": "^1.1.0",
 		"@alessiofrittoli/math-utils": "^2.0.0",
 		"@alessiofrittoli/type-utils": "^1.9.0",

package.json

@@ -0,0 +1,144 @@
+import { Exception } from '@alessiofrittoli/exception'
+
+import { cloneStyleSheets, type Styles } from '@/dom'
+import { getDimensions, type InputDimensions } from '@/utils'
+import { ErrorCode } from '@/errors'
+
+
+/**
+ * Checks if the Document Picture-in-Picture API is supported by the current browser.
+ * 
+ * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Document_Picture-in-Picture_API)
+ * 
+ * @returns `true` if Document Picture-in-Picture is supported, `false` otherwise.
+ */
+export const isDocumentPictureInPictureSupported = () => (
+	'documentPictureInPicture' in window &&
+	// @ts-expect-error ⚠️ Limited availability API.
+	typeof window.documentPictureInPicture.requestWindow === 'function'
+)
+
+
+/**
+ * Validates that the Document Picture-in-Picture API is supported in the current browser.
+ * 
+ * @throws {Exception} Throws a new Exception if the Document Picture-in-Picture API is not supported.
+ */
+export const requiresDocumentPictureInPictureAPI = () => {
+	if ( ! isDocumentPictureInPictureSupported() ) {
+		throw new Exception(
+			'The Document Picture-in-Picture API is not supported in the current browser.', {
+				code: ErrorCode.DOCUMENT_PIP_NOT_SUPPORTED,
+			}
+		)
+	}
+}
+
+
+/**
+ * Defines configuration options for opening a Document Picture-in-Picture window.
+ * 
+ */
+export interface OpenDocumentPictureInPictureOptions
+{
+	/**
+	 * A tuple defining non-negative numbers representing the width and the height to set for the Picture-in-Picture window's viewport, in pixels.
+	 * 
+	 * @default [ 250, 250 ]
+	 */
+	sizes?: InputDimensions
+	/**
+	 * Hints to the browser that it should not display a UI control that enables the user to return to the originating tab and close the Picture-in-Picture window.
+	 * 
+	 * @default false
+	 */
+	disallowReturnToOpener?: boolean
+	/**
+	 * Defines whether the Picture-in-Picture window will always appear back at the position and size it initially opened at,
+	 * when it is closed and then reopened.
+	 * 
+	 * By contrast, if `preferInitialWindowPlacement` is `false` the Picture-in-Picture window's size and position will be remembered
+	 * when closed and reopened — it will reopen at its previous position and size, for example as set by the user.
+	 * 
+	 * @default false
+	 */
+	preferInitialWindowPlacement?: boolean
+	/**
+	 * Custom styles to load inside the Picture-in-Picture window.
+	 * 
+	 * ⚠️ To keep consistent styling with your web-app, document styles are automatically cloned.
+	 */
+	styles?: Styles
+	/**
+	 * A callback to execute when Picture-in-Picture window is closed.
+	 * 
+	 */
+	onQuit?: () => void
+}
+
+
+/**
+ * Defines the returned result of opening a Document Picture-in-Picture window.
+ * 
+ */
+export interface OpenDocumentPictureInPicture
+{
+	/**
+	 * The browsing context inside the Document Picture-in-Picture window.
+	 * 
+	 */
+	window: Window
+}
+
+
+/**
+ * Opens a Document Picture-in-Picture window.
+ * 
+ * @param options Configuration options for opening a new Document Picture-in-Picture window.
+ * 	See {@link OpenDocumentPictureInPictureOptions} for more info.
+ * 
+ * @returns A new Promise that resolves to the Document Picture-in-Picture result containing the `window` of the new browsing context.
+ * 	See {@link OpenDocumentPictureInPicture} for more info.
+ * 
+ * @throws {Exception} Throws a new Exception if the Document Picture-in-Picture API is not supported.
+ * 
+ * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Document_Picture-in-Picture_API)
+ */
+export const openDocumentPictureInPicture = async (
+	options: OpenDocumentPictureInPictureOptions = {},
+): Promise<OpenDocumentPictureInPicture> => {
+
+	requiresDocumentPictureInPictureAPI()
+
+	const {
+		sizes, styles: customStyles, onQuit, ...rest
+	} = options
+
+	const [
+		width	= 250,
+		height	= width,
+	] = getDimensions( sizes )
+
+	const styles = await (
+		cloneStyleSheets( document.styleSheets )
+			.then( async result => (
+				customStyles
+					? result.concat( await cloneStyleSheets( customStyles ) )
+					: result
+			) )
+	)
+
+	// @ts-expect-error types not implemented yet.
+	const pipWindow = await window.documentPictureInPicture.requestWindow( {
+		width, height, ...rest
+	} ) as Window
+
+	styles.map( style => pipWindow.document.head.appendChild( style ) )
+
+	if ( onQuit ) {
+		pipWindow.addEventListener( 'pagehide', onQuit, { once: true } )
+	}
+
+	return { window: pipWindow }
+
+}

pnpm-lock.yaml

@@ -91,8 +91,8 @@ export type CloneStyleSheetsReturn = ( HTMLStyleElement | HTMLLinkElement )[]
  * styles.forEach( style => shadowRoot.appendChild( style ) )
  * ```
  */
-export const cloneStyleSheetList = ( styleSheets: StyleSheetList | CSSStyleSheet[] ) => (
-	[ ...styleSheets ].map( ( { cssRules } ) => {
+export const cloneStyleSheetList = ( styles: StyleSheetList | CSSStyleSheet[] ): HTMLStyleElement[] => (
+	[ ...styles ].map( ( { cssRules } ) => {
 		try {
 
 			if ( cssRules.length <= 0 ) return

src/browser-api/picture-in-picture.ts

@@ -0,0 +1,8 @@
+import { ErrorCode as Exception } from '@alessiofrittoli/exception/code';
+
+export const WebUtils = {
+	DOCUMENT_PIP_NOT_SUPPORTED: 'ERR:DOCUMENTPIPNOTSUPPORTED',
+} as const
+
+export const ErrorCode = { ...Exception, ...WebUtils }
+export type ErrorCode = ( typeof ErrorCode )[ keyof typeof ErrorCode ]