@alessiofrittoli/web-utils/dist/browser-api/sharer.d.ts

Common TypeScript web utilities

import { UrlInput } from '@alessiofrittoli/url-utils';
import { OpenBrowserPopUpOptions } from './popup.js';
import { EmailData } from '../strings.js';

/**
 * @see {@link globalThis.ShareData}
 */
interface ShareData {
    /**
     * The URL to share.
     *
     */
    url?: UrlInput;
    /**
     * An array of `File` objects representing files to be shared. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/share#shareable_file_types) for shareable file types.
     *
     */
    files?: File[];
    /**
     * A string representing text to be shared.
     *
     */
    text?: string;
    /**
     * A string representing a title to be shared. May be ignored by the target.
     *
     */
    title?: string;
}
type ClassicSharerPopUpOptions = Omit<OpenBrowserPopUpOptions, 'context'>;
interface SharerPopUpOptions extends ClassicSharerPopUpOptions {
    /**
     * The shared content title.
     *
     */
    title?: string;
}
interface OpenSharerPopUpOptions extends ClassicSharerPopUpOptions {
    /**
     * The base sharer provider URL.
     *
     */
    sharer: UrlInput;
    /**
     * Custom URLSearchParam name where URL to share get stored.
     *
     * @default 'url'
     */
    urlParam?: string;
}
interface PinterestSharerPopUpOptions extends ClassicSharerPopUpOptions {
    /**
     * The media URL.
     *
     * @default url
     */
    media?: UrlInput;
    /**
     * The media description.
     *
     */
    description?: string;
}
interface WhatsAppSharerPopUpOptions extends ClassicSharerPopUpOptions {
    /**
     * Additional custom WhatsApp message.
     *
     */
    text?: string;
}
/**
 * Check whether the web page can leverage share APIs.
 *
 * @returns	`true` if web page is running in a secure context (HTTPS) and can leverage share APIs.
 */
declare const canWebApiShare: () => boolean;
/**
 * Check whether the web page can share the given data.
 *
 * @param	data (Optional) The data that is going to be shared.
 * @returns	`true` if web page is running in a secure context (HTTPS) and can share the given data, `false` otherwise.
 */
declare const canWebApiShareData: (data?: globalThis.ShareData) => boolean;
/**
 * Share data using the native sharing mechanism of the device to share data such as text, URLs, or files.
 *
 * Available only in secure contexts.
 *
 * @param data (Optional) The data to share. If no data is provided, then the current location URL is used.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Navigator/share)
 */
declare const share: (data?: ShareData) => Promise<false | void>;
/**
 * Share data via Email.
 *
 */
declare const shareViaEmail: (data?: EmailData) => void;
/**
 * Open sharer browser PopUp.
 *
 * @param options An object defining share options. See {@link OpenSharerPopUpOptions}.
 * @returns The result of {@link openBrowserPopUp}.
 */
declare const openSharerPopUp: (options: OpenSharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on Facebook.
 *
 * @param	options	(Optional) The data to share. See {@link SharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnFacebook: (options?: SharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on Workplace.
 *
 * @param	options	(Optional) The data to share. See {@link SharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnWorkplace: (options?: SharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on Reddit.
 *
 * @param	options	(Optional) The data to share. See {@link SharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnReddit: (options?: SharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on Weibo.
 *
 * @param	options	(Optional) The data to share. See {@link ClassicSharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnWeibo: (options?: ClassicSharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on VK.
 *
 * @param	options	(Optional) The data to share. See {@link ClassicSharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnVK: (options?: ClassicSharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on Tumblr.
 *
 * @param	options	(Optional) The data to share. See {@link ClassicSharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnTumblr: (options?: ClassicSharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on Line.
 *
 * @param	options	(Optional) The data to share. See {@link ClassicSharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnLine: (options?: ClassicSharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on X.
 *
 * @param	options	(Optional) The data to share. See {@link ClassicSharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnX: (options?: ClassicSharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on LinkedIn.
 *
 * @param	options	(Optional) The data to share. See {@link ClassicSharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnLinkedIn: (options?: ClassicSharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on Telegram.
 *
 * @param	options	(Optional) The data to share. See {@link ClassicSharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnTelegram: (options?: ClassicSharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL on Pinterest.
 *
 * @param	options	(Optional) The data to share. See {@link PinterestSharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnPinterest: (options?: PinterestSharerPopUpOptions) => Window | null;
/**
 * Share URL or current page URL via WhatsApp.
 *
 * @param	options	(Optional) The data to share. See {@link WhatsAppSharerPopUpOptions} for more info.
 * @returns	The `WindowProxy` object of the new context, `null` otherwise. See {@link openBrowserPopUp} for more info.
 */
declare const shareOnWhatsApp: (options?: WhatsAppSharerPopUpOptions) => Window | null;

export { type ClassicSharerPopUpOptions, type PinterestSharerPopUpOptions, type ShareData, type SharerPopUpOptions, type WhatsAppSharerPopUpOptions, canWebApiShare, canWebApiShareData, openSharerPopUp, share, shareOnFacebook, shareOnLine, shareOnLinkedIn, shareOnPinterest, shareOnReddit, shareOnTelegram, shareOnTumblr, shareOnVK, shareOnWeibo, shareOnWhatsApp, shareOnWorkplace, shareOnX, shareViaEmail };