/** * Type definitions for uibuilder.module.js * WCAG 2.2 AA, ESLint v9, Shift-Left security, and project conventions applied. * @version 7.6.0 * @author Julian Knight (Totally Information) */ export type HtmlString = string /** Column metadata for tables */ export interface ColumnDefinition { index: number, hasName: boolean, title: string, name?: string, key?: string | number, dataType?: 'string' | 'date' | 'number' | 'html', editable?: boolean, } /** Options for building HTML tables */ export interface TableOptions { cols?: ColumnDefinition[], parent?: HTMLElement | string, allowHTML?: boolean, } /** Options for tblAddListener */ export interface TableListenerOptions { eventScope?: 'row' | 'cell', returnType?: 'text' | 'html', pad?: number, send?: boolean, logLevel?: string | number, eventType?: string, } /** Options for notification */ export interface NotificationConfig { title?: string, body?: string, return?: boolean, [key: string]: any, } /** Options for showOverlay */ export interface OverlayOptions { content?: string, title?: string, icon?: string, type?: 'success' | 'info' | 'warning' | 'error', showDismiss?: boolean, autoClose?: number | null, time?: boolean, } /** * Uibuilder main class * @typicalname uibuilder * @description The client-side Front-End JavaScript for uibuilder in HTML Module form. * Provides a number of global objects that can be used in your own JavaScript. * See the docs folder `./docs/uibuilder.module.md` for details of how to use this fully. * @version 7.6.0 * @author Julian Knight (Totally Information) */ export class Uib { /** * Static metadata for the Uibuilder client */ static _meta: { version: string, type: string, displayName: string, } /** Client ID set by uibuilder on connect */ clientId: string /** The collection of cookies provided by uibuilder */ cookies: Record /** Copy of last control msg object received from server */ ctrlMsg: object /** Is Socket.IO client connected to the server? */ ioConnected: boolean /** Is the library running from a minified version? */ isMinified: boolean /** Is the browser tab containing this page visible or not? */ isVisible: boolean /** Remember the last page (re)load/navigation type: navigate, reload, back_forward, prerender */ lastNavType: string /** Max msg size that can be sent over Socket.IO - updated by "client connect" msg receipt */ maxHttpBufferSize: number /** Last std msg received from Node-RED */ msg: object /** Number of messages sent to server since page load */ msgsSent: number /** Number of messages received from server since page load */ msgsReceived: number /** Number of control messages sent to server since page load */ msgsSentCtrl: number /** Number of control messages received from server since page load */ msgsCtrlReceived: number /** Is the client online or offline? */ online: boolean /** Last control msg object sent via uibuilder.send() */ sentCtrlMsg: object /** Last std msg object sent via uibuilder.send() */ sentMsg: object /** Placeholder to track time offset from server, see fn socket.on(ioChannels.server ...) */ serverTimeOffset: number | null /** Placeholder for a socket error message */ socketError: string | null /** Tab identifier from session storage */ tabId: string /** Actual name of current page (set in constructor) */ pageName: string | null /** Is the DOMPurify library loaded? Updated in start() */ purify: boolean /** Is the Markdown-IT library loaded? Updated in start() */ markdown: boolean /** Current URL hash. Initial set is done from start->watchHashChanges via a set to make it watched */ urlHash: string /** HTTP headers received on initial page load - contains useful uibuilder info */ httpHeaders: Record /** Default originator node id - empty string by default */ originator: string /** Optional default topic to be included in outgoing standard messages */ topic?: string /** Either undefined or a reference to a uib router instance. Set by uibrouter, do not set manually. */ uibrouterinstance?: any /** Set by uibrouter, do not set manually */ uibrouter_CurrentRoute?: any /** Internal: auto-send ready flag */ autoSendReady: boolean /** Node-RED setting (via cookie) */ httpNodeRoot: string /** Socket.IO namespace - unique to each uibuilder node instance */ ioNamespace: string /** Socket.IO path */ ioPath: string /** Starting delay factor for subsequent reconnect attempts */ retryFactor: number /** Starting retry ms period for manual socket reconnections workaround */ retryMs: number /** Prefix for all uib-related localStorage */ storePrefix: string /** Whether uibuilder client has started */ started: boolean /** Socket.IO connection options */ socketOptions: object /** How many times has the loaded instance connected to Socket.IO */ connectedNum: number /** Has the initial Socket.IO connection been made? null until first connection, then true. Used to detect if a page reload or just a disconnect/reconnect */ initialConnect: boolean | null /** How many times has the client reconnected to Socket.IO since the page was loaded. Note that this will be 0 on the initial connection */ reconnected: number /** Is Vue available? */ isVue: boolean /** Vue version if available */ vueVersion?: string /** Current transport being used by Socket.IO */ currentTransport?: string /** Last msg received from global Socket.IO namespace */ globalMsg?: any /** The URL fragment identifier for the current uib instance */ url?: string // --- Getters/Setters --- logLevel: number meta: typeof Uib._meta /** * Set uibuilder properties to a new value - works on any property except _* or #* * Also triggers any event listeners. * @param prop Any uibuilder property who's name does not start with a _ or # * @param val The set value of the property or a string declaring that a protected property cannot be changed * @param store If true, the variable is also saved to the browser localStorage if possible * @param autoload If true & store is true, on load, uib will try to restore the value from the store automatically * @returns Input value */ set(prop: string, val: any, store?: boolean, autoload?: boolean): any /** * Get the value of a uibuilder property * @param prop The name of the property to get as long as it does not start with a _ or # * @returns The current value of the property */ get(prop: string): any /** * Write to localStorage if possible. Console error output if can't write * Also uses this.storePrefix * @param id localStorage var name to be used (prefixed with 'uib_') * @param value value to write to localstore * @param autoload If true, on load, uib will try to restore the value from the store * @returns True if succeeded else false */ setStore(id: string, value: any, autoload?: boolean): boolean /** * Attempt to get and re-hydrate a key value from localStorage * @param id The key of the value to attempt to retrieve * @returns The re-hydrated value of the key or null if key not found, undefined on error */ getStore(id: string): any /** * Remove a given id from the uib keys in localStorage * @param id The key to remove */ removeStore(id: string): void /** * Returns a list of the externally accessible command functions that are available to be called from Node-RED * @returns List of externally accessible command functions */ getCommandList(): string[] /** * Returns a list of uibuilder properties (variables) that can be watched with onChange * @returns List of uibuilder managed variables */ getManagedVarList(): Record /** * Returns a list of currently watched variables * @returns List of watched variable names */ getWatchedVars(): string[] /** * Register on-change event listeners for uibuilder tracked properties * @param prop The property of uibuilder that we want to monitor * @param callback The function that will run when the property changes, parameter is the new value of the property after change * @returns A reference to the callback to cancel */ onChange(prop: string, callback: (val: any) => void): number /** * Cancel a previously registered onChange event listener * @param prop The property name * @param cbRef The callback reference number */ cancelChange(prop: string, cbRef: number): void /** * Register a change callback for a specific msg.topic * @param topic The msg.topic we want to listen for * @param callback The function that will run when an appropriate msg is received * @returns A reference to the callback to cancel */ onTopic(topic: string, callback: (msg: any) => void): number /** * Cancel a previously registered onTopic event listener * @param topic The topic name * @param cbRef The callback reference number */ cancelTopic(topic: string, cbRef: number): void /** * Returns a new array containing the intersection of the 2 input arrays * @param a1 Array to check * @param a2 Array to intersect * @returns The intersection of the 2 arrays (may be an empty array) */ arrayIntersect(a1: T[], a2: T[]): T[] /** * Check if an attribute name is a uibuilder-specific attribute. * Matches names starting with 'uib-', 'data-uib-', or ':'. * @param name The attribute name to check * @returns True if the attribute name is a uib attribute */ isUibAttribute(name: string): boolean /** * Copies a uibuilder variable to the browser clipboard * @param varToCopy The name of the uibuilder variable to copy to the clipboard */ copyToClipboard(varToCopy: string): void /** * Does the chosen CSS Selector currently exist? * @param cssSelector Required. CSS Selector to examine for visibility * @param msg Optional, default=true. If true also sends a message back to Node-RED * @returns True if the element exists */ elementExists(cssSelector: string, msg?: boolean): boolean /** * Format a Date using Intl with optional pattern support * @param date Input JS Date, date string, or timestamp * @param pattern Optional pattern string * @param locale Locale code. Defaults to browser locale. * @returns Formatted date string */ formatDate(date: Date | string | number, pattern?: string, locale?: string): string /** * Format a number using the INTL standard library * @param value Number to format * @param decimalPlaces Number of decimal places to include * @param intl standard locale spec, e.g. "ja-JP" or "en-GB" * @param opts INTL library options object * @returns formatted number */ formatNumber(value: number, decimalPlaces?: number, intl?: string, opts?: object): string /** * Attempt to get rough size of an object * @param obj Any serialisable object * @returns Rough size of object in bytes or undefined */ getObjectSize(obj: any): number | undefined /** * Returns true if a uibrouter instance is loaded, otherwise returns false * @returns true if uibrouter instance loaded else false */ hasUibRouter(): boolean /** * Only keep the URL Hash & ignoring query params * @param url URL to extract the hash from * @returns Just the route id */ keepHashFromUrl(url: string): string /** * Custom logging function * @param args Arguments to log */ log(...args: any[]): void /** Output the current call stack to the console */ logStack(): void /** * Get the current call stack as an array of objects * @returns Stack array with file, function, line, column and raw entries */ stack(): Array<{ file?: string, function?: string, line?: number, column?: number, raw: string }> /** * Create and return a randomised UUID * Uses the browsers crypto library if available (newer browsers) * or something based on the timestamp and a random number * @returns The UUID */ randomUUID(): string /** * Makes a null or non-object into an object. If thing is already an object. * If not null, moves "thing" to {payload:thing} * @param thing Thing to check * @param property property that "thing" is moved to if not null and not an object. Default='payload' * @returns Object */ makeMeAnObject(thing: any, property?: string): object /** * Navigate to a new page or a new route (hash) * @param url URL to navigate to. Can be absolute or relative (to current page) or just a hash for a route change * @returns The new window.location string */ navigate(url: string): Location /** * Scroll the page or a specific element into view * @param cssSelector Optional. If not set, scrolls to top of page. Can also be 'top'|'start'|'bottom'|'end' * @param opts Optional DOM scrollIntoView options * @returns True if element was found (or top/bottom handled), false otherwise */ scrollTo(cssSelector?: string, opts?: { block?: string, inline?: string, behavior?: string }): boolean /** * Convert a string attribute into a variable/constant reference * Used to resolve data sources in attributes * @param path The string path to resolve, must be relative to the `window` global scope * @returns The resolved data source or null */ resolveDataSource(path: string): any /** * Fast but accurate number rounding * @param num The number to be rounded * @param decimalPlaces Number of DP's to round to * @returns Rounded number */ round(num: number, decimalPlaces: number): number /** * Promise-based (async) sleep utility * @param ms Milliseconds to sleep * @returns Resolves after the specified time */ sleep(ms: number): Promise /** * Creates a sandboxed evaluator function for string expressions that can reference properties on a provided context object * Uses the Function constructor to create a new function with the context passed as an argument * @param expression The expression to evaluate * @returns Evaluator function */ createSafeEvaluator(expression: string): Function /** * Safe expression evaluator that will retry several times if variables are not yet available * Defaults to false if still not successful after retries * @param expression The expression to evaluate (e.g., "pageData.status || pageData.since") * @param context The context object containing variables (e.g., { pageData }) * @param options Configuration options (maxRetries, retryDelay, defaultValue) * @returns Resolves to the evaluated result or defaultValue */ evaluateWithRetry(expression: string, context: object, options?: { maxRetries?: number, retryDelay?: number, defaultValue?: any }): Promise /** * Set the default originator. Set to '' to ignore. Used with uib-sender. * @param originator A Node-RED node ID to return the message to */ setOriginator(originator?: string): void /** * HTTP Ping/Keep-alive - makes a call back to uibuilder's ExpressJS server and receives a 204 response * Can be used to keep sessions alive. * @param ms Repeat interval in ms */ setPing(ms?: number): void /** * Convert JSON to Syntax Highlighted HTML * @param json A JSON/JavaScript Object * @returns Object reformatted as highlighted HTML */ syntaxHighlight(json: object): HtmlString /** * Returns true/false or a default value for truthy/falsy and other values * @param val The value to test * @param deflt Default value to use if the value is not truthy/falsy * @returns The truth! Or the default */ truthy(val: any, deflt: any): boolean | any /** * Joins all arguments as a URL string * @param paths URL fragments * @returns Joined URL string */ urlJoin(...paths: string[]): string /** * Turn on/off/toggle sending URL hash changes back to Node-RED * @param toggle Optional on/off/etc * @returns True if we will send a msg to Node-RED on a hash change */ watchUrlHash(toggle?: any): boolean /** * DEPRECATED FOR NOW - wasn't working properly. * Is the chosen CSS Selector currently visible to the user? NB: Only finds the FIRST element of the selection. * @returns False */ elementIsVisible(): false // --- UI handlers --- /** * Simplistic jQuery-like document CSS query selector, returns an HTML Element. * If the selected element is a