@etsoo/shared/lib/mjs/DomUtils.d.ts

TypeScript shared utilities and functions

import { DataTypes } from "./DataTypes";
import { ErrorData, ErrorType } from "./types/ErrorData";
import { FormDataFieldValue, IFormData } from "./types/FormData";
/**
 * User agent data, maybe replaced by navigator.userAgentData in future
 * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgentData
 */
export type UserAgentData = {
    /**
     * Browser brands
     */
    brands: {
        brand: string;
        version: string;
    }[];
    /**
     * Is mobile device
     */
    mobile: boolean;
    /**
     * Device brand (name)
     */
    device: string;
    /**
     * Platform (OS)
     */
    platform: string;
    /**
     * Platform version
     */
    platformVersion?: string;
};
/**
 * Dom Utilities
 * Not all methods support Node
 */
export declare namespace DomUtils {
    /**
     * Language cache parameter name
     */
    const CultureField = "culture";
    /**
     * Country cache parameter name
     */
    const CountryField = "country";
    /**
     * Clear form data
     * @param data Form data
     * @param source Source data to match
     * @param keepFields Fields need to be kept
     */
    function clearFormData(data: IFormData, source?: object, keepFields?: string[]): IFormData;
    /**
     * Cast data as template format
     * @param source Source data
     * @param template Format template
     * @param keepSource Keep other source properties
     * @returns Result
     */
    function dataAs<T extends DataTypes.BasicTemplate>(source: unknown, template: T, keepSource?: boolean): DataTypes.BasicTemplateType<T>;
    /**
     * Cast data to target type
     * @param source Source data
     * @param template Template for generation
     * @param keepSource Means even the template does not include the definition, still keep the item
     * @returns Result
     */
    function dataValueAs<T extends object>(source: IFormData | object, templateValue: T, keepSource?: boolean): Partial<T>;
    /**
     * Current detected country
     */
    const detectedCountry: string | null;
    /**
     * Current detected culture
     */
    const detectedCulture: string;
    /**
     * Is two dimensions equal
     * @param d1 Dimension 1
     * @param d2 Dimension 2
     */
    function dimensionEqual(d1?: DOMRect, d2?: DOMRect): boolean;
    /**
     * Download file from API fetch response body
     * @param data Data
     * @param suggestedName Suggested file name
     * @param autoDetect Auto detect, false will use link click way
     */
    function downloadFile(data: ReadableStream | Blob, suggestedName?: string, autoDetect?: boolean): Promise<boolean | undefined>;
    /**
     * File to data URL
     * @param file File
     * @returns Data URL
     */
    function fileToDataURL(file: File): Promise<string>;
    /**
     * Form data to object
     * @param form Form data
     * @returns Object
     */
    function formDataToObject(form: IFormData): Record<string, FormDataFieldValue | FormDataFieldValue[]>;
    /**
     * Is wechat client
     * @param data User agent data
     * @returns Result
     */
    function isWechatClient(data?: UserAgentData | null): boolean;
    /**
     * Culture match case Enum
     */
    enum CultureMatch {
        Exact = 0,
        Compatible = 1,
        SamePart = 2,
        Default = 3
    }
    /**
     * Get English resources definition
     * @param resources Resources
     * @returns Result
     */
    const en: <T extends DataTypes.StringRecord = DataTypes.StringRecord>(resources: T | (() => Promise<T>)) => DataTypes.CultureDefinition<T>;
    /**
     * Get simplified Chinese resources definition
     * @param resources Resources
     * @returns Result
     */
    const zhHans: <T extends DataTypes.StringRecord = DataTypes.StringRecord>(resources: T | (() => Promise<T>)) => DataTypes.CultureDefinition<T>;
    /**
     * Get traditional Chinese resources definition
     * @param resources Resources
     * @returns Result
     */
    const zhHant: <T extends DataTypes.StringRecord = DataTypes.StringRecord>(resources: T | (() => Promise<T>)) => DataTypes.CultureDefinition<T>;
    /**
     * Get the available culture definition
     * @param items Available cultures
     * @param culture Detected culture
     */
    const getCulture: <T extends DataTypes.StringRecord>(items: DataTypes.CultureDefinition<T>[], culture: string) => [DataTypes.CultureDefinition<T>, CultureMatch];
    /**
     * Get input value depending on its type
     * @param input HTML input
     * @returns Result
     */
    function getInputValue(input: HTMLInputElement): string | number | Date | null | undefined;
    /**
     * Get an unique key combined with current URL
     * @param key Key
     */
    const getLocationKey: (key: string) => string;
    /**
     * Convert headers to object
     * @param headers Heaers
     */
    function headersToObject(headers: HeadersInit | Iterable<[string, string]>): Record<string, string>;
    /**
     * Is IFormData type guard
     * @param input Input object
     * @returns result
     */
    function isFormData(input: unknown): input is IFormData;
    /**
     * Is JSON content type
     * @param contentType Content type string
     */
    function isJSONContentType(contentType: string): boolean;
    /**
     * Merge form data to primary one
     * @param form Primary form data
     * @param forms Other form data
     * @returns Merged form data
     */
    function mergeFormData(form: IFormData, ...forms: IFormData[]): IFormData;
    /**
     * Merge URL search parameters
     * @param base URL search parameters
     * @param data New simple object data to merge
     */
    function mergeURLSearchParams(base: URLSearchParams, data: DataTypes.SimpleObject): URLSearchParams;
    /**
     * Parse navigator's user agent string
     * Lightweight User-Agent string parser
     * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent
     * @param ua User agent string
     * @returns User agent data
     */
    function parseUserAgent(ua?: string): UserAgentData | null;
    /**
     * Set HTML element focus by name
     * @param name Element name or first collection item
     * @param container Container, limits the element range
     */
    function setFocus(name: string | object, container?: HTMLElement): void;
    /**
     * Setup frontend logging
     * @param action Logging action
     * @param preventDefault Is prevent default action
     * @param window Window object
     */
    function setupLogging(action: (data: ErrorData) => void | Promise<void>, preventDefault?: ((type: ErrorType) => boolean) | boolean, window?: Window & typeof globalThis): void;
    /**
     * Verify file system permission
     * https://developer.mozilla.org/en-US/docs/Web/API/FileSystemHandle/requestPermission
     * @param fileHandle FileSystemHandle
     * @param withWrite With write permission
     * @returns Result
     */
    function verifyPermission(fileHandle: any, withWrite?: boolean): Promise<boolean>;
}