fomantic-ui 2.9.3-beta.9 → 2.9.4-beta.0

package/types/fomantic-ui-api.d.ts

@@ -0,0 +1,555 @@
+declare namespace FomanticUI {
+    interface API {
+        settings: APISettings;
+
+        /**
+         * Execute query using existing API settings.
+         */
+        (behavior: 'query'): JQuery;
+
+        /**
+         * Adds data to existing templated url and returns full url string.
+         */
+        (behavior: 'add url data', url: string, data: any): JQuery;
+
+        /**
+         * Gets promise for current API request.
+         */
+        (behavior: 'get request'): JQuery;
+
+        /**
+         * Aborts current API request.
+         */
+        (behavior: 'abort'): JQuery;
+
+        /**
+         * Returns whether last request was cancelled.
+         */
+        (behavior: 'was cancelled'): boolean;
+
+        /**
+         * Returns whether last request was failure.
+         */
+        (behavior: 'was failure'): boolean;
+
+        /**
+         * Returns whether last request was successful.
+         */
+        (behavior: 'was successful'): boolean;
+
+        /**
+         * Returns whether last request was completed.
+         */
+        (behavior: 'was complete'): boolean;
+
+        /**
+         * Returns whether element is disabled.
+         */
+        (behavior: 'is disabled'): boolean;
+
+        /**
+         * Returns whether element response is mocked.
+         */
+        (behavior: 'is mocked'): boolean;
+
+        /**
+         * Returns whether element is loading.
+         */
+        (behavior: 'is loading'): boolean;
+
+        /**
+         * Sets loading state to element.
+         */
+        (behavior: 'set loading'): void;
+
+        /**
+         * Sets error state to element.
+         */
+        (behavior: 'set error'): void;
+
+        /**
+         * Removes loading state to element.
+         */
+        (behavior: 'remove loading'): void;
+
+        /**
+         * Removes error state to element.
+         */
+        (behavior: 'remove error'): void;
+
+        /**
+         * Gets event that API request will occur on.
+         */
+        (behavior: 'get event'): string;
+
+        /**
+         * Returns 'encodeURIComponent' value only if value passed is not already encoded.
+         */
+        (behavior: 'get url encoded value', value: any): string;
+
+        /**
+         * Reads a locally cached response for a URL.
+         */
+        (behavior: 'read cached response', url: string): any;
+
+        /**
+         * Writes a cached response for a URL.
+         */
+        (behavior: 'write cached response', url: string, response: any): void;
+
+        /**
+         * Creates new cache, removing all locally cached URLs.
+         */
+        (behavior: 'create cache'): void;
+
+        /**
+         * Removes API settings from the page and all events.
+         */
+        (behavior: 'destroy'): JQuery;
+
+        <K extends keyof APISettings | JQueryAjaxSettings>(behavior: 'setting', name: K, value?: undefined, ): Partial<Pick<APISettings, keyof APISettings>> | Partial<Pick<JQueryAjaxSettings, keyof JQueryAjaxSettings>>;
+        <K extends keyof APISettings>(behavior: 'setting', name: K, value: APISettings[K]): JQuery;
+        (behavior: 'setting', value: Partial<Pick<APISettings, keyof APISettings>> | Partial<Pick<JQueryAjaxSettings, keyof JQueryAjaxSettings>>): JQuery;
+        (settings?: Partial<Pick<APISettings, keyof APISettings>> | Partial<Pick<JQueryAjaxSettings, keyof JQueryAjaxSettings>>): JQuery;
+    }
+
+    /**
+     * @see {@link https://fomantic-ui.com/behaviors/api.html#/settings}
+     */
+    interface APISettings {
+        // region API Settings
+
+        /**
+         * When API event should occur.
+         * @default 'auto'
+         */
+        on: string;
+
+        /**
+         * Can be set to 'local' to cache successful returned AJAX responses when using a JSON API.
+         * This helps avoid server roundtrips when API endpoints will return the same results when accessed repeatedly.
+         * Setting to 'false', will add cache busting parameters to the URL.
+         * @default true
+         */
+        cache: boolean | 'local';
+
+        /**
+         * UI state will be applied to this element, defaults to triggering element.
+         * @default false
+         */
+        stateContext: false | JQuery;
+
+        /**
+         * Whether to encode parameters with 'encodeURIComponent' before adding into url string.
+         * @default true
+         */
+        encodeParameters: boolean;
+
+        /**
+         * Whether to automatically include default data like {value} and {text}.
+         * @default true
+         */
+        defaultData: boolean;
+
+        /**
+         * Whether to serialize closest form and include in request.
+         * Use `true` to convert complex named keys like `a[b][1][c][]` into a nested object
+         * Use `formdata` for formdata web api
+         * @default false
+         */
+        serializeForm: boolean;
+
+        /**
+         * How long to wait when a request is made before triggering request, useful for rate limiting 'oninput'.
+         * @default 0
+         */
+        throttle: number;
+
+        /**
+         * When set to false will not delay the first request made, when no others are queued.
+         * @default true
+         */
+        throttleFirstRequest: boolean;
+
+        /**
+         * Whether an API request can occur while another request is still pending.
+         * @default false
+         */
+        interruptRequests: boolean;
+
+        /**
+         * Minimum duration to show loading indication.
+         * @default 0
+         */
+        loadingDuration: number;
+
+        /**
+         * The default 'auto' will automatically remove error state after error duration, unless the element is a 'form'.
+         * @default 'auto'
+         */
+        hideError: 'auto' | boolean;
+
+        /**
+         * Setting to 'true', will not remove error. Setting to a duration in milliseconds to show error state after request error.
+         * @default 2000
+         */
+        errorDuration: true | number;
+
+        // endregion
+
+        // region API Settings
+
+        /**
+         * Named API action for query, originally specified in '$.fn.settings.api'.
+         * @default false
+         */
+        action: string | false;
+
+        /**
+         * Templated URL for query, will override specified action.
+         * @default false
+         */
+        url: string | false;
+
+        /**
+         * base URL to apply to all endpoints. Will be prepended to each given url.
+         * @default ''
+         */
+        base: string;
+
+        /**
+         * Variables to use for replacement.
+         * @default false
+         */
+        urlData: any;
+
+        /**
+         * Can be set to a Javascript object which will be returned automatically instead of requesting JSON from server.
+         * @default false
+         */
+        response: any;
+
+        /**
+         * When specified, this function can be used to retrieve content from a server and return it asynchronously instead of a standard AJAX call.
+         * The callback function should return the server response.
+         * @default false
+         */
+        responseAsync: ((settings: APISettings, callback: (response: any) => void) => void) | false;
+
+        /**
+         * Alias of 'response'.
+         * @default false
+         */
+        mockResponse: any;
+
+        /**
+         * Alias of 'responseAsync'.
+         * @default false
+         */
+        mockResponseAsync: ((settings: APISettings, callback: (response: any) => void) => void) | false;
+
+        /**
+         * If set, the onResponse event handler is able to handle an raw Array Object, which is probably returned by the requested source.
+         * Even if the datatype is json, it won't be force converted into an object anymore then.
+         * @default true
+         */
+        rawResponse: boolean;
+
+        /**
+         * Method for transmitting request to server.
+         * @default 'get'
+         */
+        method: 'get' | 'post' | 'put' | 'delete' | 'head' | 'options' | 'patch';
+
+        /**
+         * Expected data type of response.
+         * @default 'json'
+         */
+        dataType: 'xml' | 'json' | 'jsonp' | 'script' | 'html' | 'text';
+
+        /**
+         * Expected data type of response.
+         * @default {}
+         */
+        data: any;
+
+        // endregion
+
+        // region Callbacks
+
+        /**
+         * Allows modifying settings before request, or cancelling request.
+         */
+        beforeSend(settings: APISettings): any;
+
+        /**
+         * Allows modifying XHR object for request.
+         */
+        beforeXHR(xhrObject: JQuery.jqXHR): any;
+
+        /**
+         * Callback that occurs when request is made. Receives both the API success promise and the XHR request promise.
+         */
+        onRequest(promise: JQuery.Deferred<any>, xhr: JQuery.jqXHR): void;
+
+        /**
+         * Allows modifying the server's response before parsed by other callbacks to determine API event success.
+         */
+        onResponse(response: any): void;
+
+        /**
+         * Determines whether completed JSON response should be treated as successful.
+         *
+         * @see {@link http://fomantic-ui.com/behaviors/api.html#determining-json-success}
+         */
+        successTest(response: any): boolean;
+
+        /**
+         * Callback after successful response, JSON response must pass 'successTest'.
+         */
+        onSuccess(response: any, element: JQuery, xhr: JQuery.jqXHR): void;
+
+        /**
+         * Callback on request complete regardless of conditions.
+         */
+        onComplete(response: any, element: JQuery, xhr: JQuery.jqXHR): void;
+
+        /**
+         * Callback on failed response, or JSON response that fails 'successTest'.
+         */
+        onFailure(response: any, element: JQuery): void;
+
+        /**
+         * Callback on server error from returned status code, or XHR failure.
+         */
+        onError(errorMessage: string, element: JQuery, xhr: JQuery.jqXHR): void;
+
+        /**
+         * Callback on abort caused by user clicking a link or manually cancelling request.
+         */
+        onAbort(errorMessage: string, element: JQuery, xhr: JQuery.jqXHR): void;
+
+        // endregion
+
+        // region DOM Settings
+
+        /**
+         * Selectors used to find parts of a module.
+         */
+        selector: API.SelectorSettings;
+
+        /**
+         * Class names used to determine element state.
+         */
+        className: API.ClassNameSettings;
+
+        /**
+         * Regular expressions used for template matching.
+         */
+        regExp: API.RegExpSettings;
+
+        /**
+         * Metadata used to store XHR and response promise.
+         */
+        metadata: API.MetadataSettings;
+
+        // endregion
+
+        // region Debug Settings
+
+        /**
+         * Name used in log statements.
+         * @default 'API'
+         */
+        name: string;
+
+        /**
+         * Event namespace. Makes sure module teardown does not effect other events attached to an element.
+         * @default 'api'
+         */
+        namespace: string;
+
+        /**
+         * Silences all console output including error messages, regardless of other debug settings.
+         * @default false
+         */
+        silent: boolean;
+
+        /**
+         * Debug output to console.
+         * @default false
+         */
+        debug: boolean;
+
+        /**
+         * Show 'console.table' output with performance metrics.
+         * @default true
+         */
+        performance: boolean;
+
+        /**
+         * Debug output includes all internal behaviors.
+         * @default false
+         */
+        verbose: boolean;
+
+        errors: API.ErrorSettings;
+
+        // endregion
+    }
+
+    namespace API {
+        type SelectorSettings = Partial<Pick<Settings.Selectors, keyof Settings.Selectors>>;
+        type ClassNameSettings = Partial<Pick<Settings.ClassNames, keyof Settings.ClassNames>>;
+        type RegExpSettings = Partial<Pick<Settings.RegExps, keyof Settings.RegExps>>;
+        type MetadataSettings = Partial<Pick<Settings.Metadatas, keyof Settings.Metadatas>>;
+        type ErrorSettings = Partial<Pick<Settings.Errors, keyof Settings.Errors>>;
+
+        namespace Settings {
+            interface Selectors {
+                /**
+                 * @default '.disabled'
+                 */
+                disabled: string;
+
+                /**
+                 * @default 'form'
+                 */
+                form: string;
+            }
+
+            interface ClassNames {
+                /**
+                 * @default 'loading'
+                 */
+                loading: string;
+
+                /**
+                 * @default 'error'
+                 */
+                error: string;
+            }
+
+            interface RegExps {
+                /**
+                 * @default /{\$*[\da-z]+}/gi
+                 */
+                required: RegExp;
+
+                /**
+                 * @default /{\/\$*[\da-z]+}/gi
+                 */
+                optional: RegExp;
+
+                /**
+                 * @default /^[_a-z][\w-]*(?:\[[\w-]*])*$/i
+                 */
+                validate: RegExp;
+
+                /**
+                 * /[\w-]+|(?=\[])/gi
+                 */
+                key: RegExp;
+
+                /**
+                 * @default /^$/
+                 */
+                push: RegExp;
+
+                /**
+                 * @default /^\d+$/
+                 */
+                fixed: RegExp;
+
+                /**
+                 * @default /^[\w-]+$/i
+                 */
+                named: RegExp;
+            }
+
+            interface Metadatas {
+                /**
+                 * @default 'action'
+                 */
+                action: string;
+
+                /**
+                 * @default 'url'
+                 */
+                url: string;
+            }
+
+            interface Errors {
+                /**
+                 * @default 'The before send function has aborted the request.'
+                 */
+                beforeSend: string;
+
+                /**
+                 * @default 'There was an error with your request.'
+                 */
+                error: string;
+
+                /**
+                 * @default 'API Request Aborted. Exit conditions met.'
+                 */
+                exitConditions: string;
+
+                /**
+                 * @default 'JSON could not be parsed during error handling.'
+                 */
+                JSONParse: string;
+
+                /**
+                 * @default 'You are using legacy API success callback names.'
+                 */
+                legacyParameters: string;
+
+                /**
+                 * @default 'The method you called is not defined.'
+                 */
+                method: string;
+
+                /**
+                 * @default 'API action used but no url was defined.'
+                 */
+                missingAction: string;
+
+                /**
+                 * @default 'No URL specified for API event.'
+                 */
+                missingURL: string;
+
+                /**
+                 * @default 'The beforeSend callback must return a settings object, beforeSend ignored.'
+                 */
+                noReturnedValue: string;
+
+                /**
+                 * @default 'There was an error with your request.'
+                 */
+                parseError: string;
+
+                /**
+                 * @default 'Caching responses locally requires session storage.'
+                 */
+                noStorage: string;
+
+                /**
+                 * @default 'Missing a required URL parameter: '
+                 */
+                requiredParameter: string;
+
+                /**
+                 * @default 'Server gave an error: '
+                 */
+                statusMessage: string;
+
+                /**
+                 * @default 'Your request timed out.'
+                 */
+                timeout: string;
+            }
+        }
+    }
+}