@ideal-postcodes/postcode-lookup/esm/controller.d.ts

UK Postcode Lookup plugin from Ideal Postcodes

/**
 * @module Controller
 */
import { Client } from "@ideal-postcodes/core-axios";
import { Config as ClientConfig } from "@ideal-postcodes/core-axios/dist/client";
import { GbrAddress } from "@ideal-postcodes/jsutil";
import { Config } from "./index";
/**
 * Keypress listener on input field
 *
 * @hidden
 */
export declare const keypress: (this: Controller, event: KeyboardEvent) => false | undefined;
/**
 * Button Click handler
 *
 * @hidden
 */
export declare const click: (this: Controller, event: Event) => boolean;
/**
 * Select change handler
 *
 * @hidden
 */
export declare const selectEvent: (this: Controller) => void;
/**
 * Default Controller configuration
 */
export declare const defaults: StrictConfig;
/**
 * @hidden
 */
export declare type StrictConfig = Required<Omit<Config, "document" | "scope">>;
/**
 * Configuration object for `Controller`
 */
export interface ControllerConfig extends Config, Omit<ClientConfig, "api_key"> {
}
/**
 * @hidden
 */
interface CachedOptions extends Required<Config>, Omit<ClientConfig, "api_key"> {
}
/**
 * A Postcode Lookup Controller instances manages the state of a postcode or address search widget and updates the DOM accordingly
 *
 * To detach from the DOM call use the `#removeAll()` method
 */
export declare class Controller {
    /**
     * Caches options object
     */
    options: CachedOptions;
    /**
     * Stores most recent lookup
     */
    lastLookup: string;
    /**
     * Cache for recently retrieved data
     */
    data: GbrAddress[];
    /**
     * Ideal Postcodes API client
     */
    client: Client;
    /**
     * Scopes the DOM for the entire controller
     */
    scope: HTMLElement | Document;
    /**
     * Scopes the DOM for fields which should receive address inputs
     */
    outputScope: HTMLElement | Document;
    /**
     * Reference to the DOM, to which this.scope belongs
     */
    document: Document;
    /**
     * HTML Element in which postcode lookup tools live
     */
    context: HTMLElement;
    /**
     * Reference to postcode lookup input field
     */
    input: HTMLInputElement;
    /**
     * Reference to postcode lookup button
     */
    button: HTMLButtonElement;
    /**
     * Reference to message paragraph element
     */
    message: HTMLParagraphElement;
    /**
     * Reference to dropdown containing address suggestions
     */
    select: HTMLSelectElement;
    /**
     * Reference to HTMLElement that wraps the <select> address dropdown
     */
    selectContainer: HTMLElement;
    /**
     * Clickable element that triggers unhiding of address fields if enabled
     */
    unhide: HTMLElement;
    private click;
    private keypress;
    private selectEvent;
    private unhideEvent;
    private prevContext;
    constructor(options: ControllerConfig);
    /**
     * Retrieve Element
     * - If string, assumes is valid and returns first match within scope
     * - If null, invokes the create method to return a default
     * - If HTMLElement returns instance
     *
     * @hidden
     */
    findOrCreate<T>(q: string | null | T, create?: () => T): T;
    /**
     * Creates a clickable element that can trigger unhiding of fields
     */
    createUnhide(): HTMLElement;
    /**
     * Removes unhide elem from DOM
     */
    unmountUnhide(): void;
    /**
     * Creates select container instance
     *
     * @hidden
     */
    createContainer(): HTMLDivElement;
    /**
     * Removes select container from DOM
     */
    unmountContainer(): void;
    /**
     * Create input field and binds event listeners
     *
     * - If a selector (this.input) is specified, that input is used
     * - If no selector specified, a new input field is generated and added to context
     *
     * @hidden
     */
    createInput(): HTMLInputElement;
    /**
     * Removes address input artefacts from DOM
     * - Removes event listeners from input field
     * - Removes input field, unless input field is provided by the user
     */
    unmountInput(): void;
    /**
     * Creates button and binds event listeners
     *
     * @hidden
     */
    createButton(): HTMLButtonElement;
    /**
     * unmountButton
     * - Remove listener events
     * - Remove button from DOM if generated by this controller
     */
    unmountButton(): void;
    /**
     * Mounts message container
     *
     * @hidden
     */
    createMessage(): HTMLParagraphElement;
    /**
     * Removes message container from DOM
     */
    unmountMessage(): void;
    /**
     * Creates Select HTML Element
     */
    createSelect(): HTMLSelectElement;
    /**
     * Mounts dropdown menu to DOM and attach event listeners
     *
     * Removes dropdown from DOM if data is undefined
     */
    mountSelect(data?: GbrAddress[], nextPage?: number): void;
    /**
     * Remove dropdown from DOM
     */
    unmountSelect(): void;
    /**
     * Selects an address by its offset `i` in the list of address results
     */
    selectAddress(i: number): void;
    /**
     * Callback for address search click event
     *
     * @hidden
     */
    handleClick(): false;
    /**
     * Prevents lookup button from being triggered
     */
    disableButton(message?: string): void;
    /**
     * Enables lookup button to trigger searches
     */
    enableButton(): void;
    /**
     * Allows lookup button to be triggered and applies a cooloff timer if configured
     */
    enableLookup(): void;
    /**
     * Resets address search fields
     * - Removes any existing address selection dropdown
     * - Removes any visiable messages
     */
    reset(): void;
    /**
     * Removes all elements from DOM including dropdown, input, button and any error message
     * - Remove all event listeners
     * - Remove non-custom elements DOM
     */
    removeAll(): void;
    /**
     * Returns not found message
     *
     * @hidden
     */
    notFoundMessage(): string;
    /**
     * Triggers a search based on term and mounts addresses to DOM in the address
     * dropdown
     *
     * Validate search term and then trigger postcode lookup
     *  - On successful search, display results in a dropdown menu
     *  - On successful search but no addresses, show error message
     *  - On failed search, show error message
     */
    executeSearch(term: string, page?: number): Promise<void>;
    suggestionsMessage(suggestions: string[]): void;
    /**
     * Invoke postcode lookup
     *
     * @hidden
     */
    searchPostcode(postcode: string, page?: number): Promise<{
        addresses: GbrAddress[];
        page: number;
        total: number;
        limit: number;
    }>;
    /**
     * Invoke an address search
     *
     * @hidden
     */
    searchAddress(query: string, _?: number): Promise<{
        addresses: GbrAddress[];
        page: number;
        total: number;
        limit: number;
    }>;
    /**
     * Formats address according to whether text or postcode search is active
     *
     * @hidden
     */
    formatAddress(address: GbrAddress): string;
    createOption(value: string, text: string): HTMLOptionElement;
    /**
     * Sets the error message
     *
     * Removes error message from DOM if undefined
     */
    setMessage(message?: string): void;
    /**
     * Hides any messages
     */
    hideMessage(): void;
    /**
     * Call to initially render the DOM elements
     *
     * This will perform an optional keyCheck if required
     */
    init(): void;
    /**
     * Writes a selected to the input fields specified in the controller config
     */
    populateAddress(address: GbrAddress): void;
    hiddenFields(): HTMLElement[];
    /**
     * Hides fields marked for hiding
     */
    hideFields(): void;
    /**
     * Unhides fields marked for hiding and triggers callback
     */
    unhideFields(): void;
    /**
     * Empties context and appends postcode lookup input, button, message field
     * and select container
     *
     * Does not render element if a custom element has been provided
     */
    render(): void;
}
export {};