feat: Provide TypeScript type definition file

[pahund]

Allow TypeScript projects to easily integrate react-advertising by providing a type definition file.

[juanpicado]

Would this include migrate to TS? or just the definition file?

[pahund]

@juanpicado Let's start with just the definition file.

[juanpicado]

Please someone else take it, I won't be able to work on it this month, otherwise, I'll pick it up again next month if still open.

[ahtcx]

Here's a incomplete version I have for one of our projects, just put it in a .d.ts file in your project:

declare module "react-advertising" {
	export type Size = [width: number, height: number];

	export interface SizeMapping {
		/** The target view port size of the size mapping; array with two numbers for width and height */
		viewPortSize: Size;

		/**
		 * Array of ad sizes to be displayed in this view port; array of arrays with two numbers for width and height
		 *  - ⚠️ important: this needs to be an array, even if you have only one ad size to display for this viewport size
		 *  - If you want to display no ads for this size, specify an empty array (`[]`)
		 */
		sizes: Size[];
	}

	export interface Slot<SizeMappingName extends string> {
		/** slot ID */
		id: string;

		/** slot's ad unit path */
		path?: string;

		/** configuration for removing empty slots */
		collapseEmptyDivs?: boolean | boolean[];

		/** targeting parameters and other key-values specific to the slot */
		targeting?: Record<string, string>;

		/** slot size configuration for GPT */
		sizes?: unknown;

		/** slot size configuration for GPT */
		sizeMappingName?: SizeMappingName;

		/** configuration to lazy load this ad slot */
		enableLazyLoad?: unknown;

		/** array with slot's Prebid configuration objects */
		prebid?: unknown;
	}

	export interface AdvertisingConfiguration<
		SizeMappings extends Record<string, SizeMapping[]>,
	> {
		/** global ad unit path, used if not specified in a slot */
		path?: string;

		/** global GPT targeting parameters and other key-values */
		targeting?: Record<string, string>;

		/** GPT size mapping definitions */
		sizeMappings?: SizeMappings;

		/** global Prebid configuration */
		prebid?: unknown;

		/** Turn use of Prebid on or off */
		usePrebid?: boolean;

		/** configuration of custom events dispatched by the creatives */
		customEvents?: unknown;

		/** configuration to lazy load all ads */
		enableLazyLoad?: unknown;

		/** array of slot configurations */
		slots: Slot<keyof SizeMappings>[];

		/** array of outOfPageSlot configurations */
		outOfPageSlots?: { id: string }[];
	}

	export interface AdvertisingProviderProps {
		children?: React.ReactNode;
		config?: AdvertisingConfiguration;
	}

	export function AdvertisingProvider(
		props: AdvertisingProviderProps,
	): JSX.Element;

	export interface AdvertisingSlotProps {
		className?: string;
		id: string;
		style?: React.CSSProperties;
	}

	export function AdvertisingSlot(props: AdvertisingSlotProps): ReactElement;
}