@wailsio/runtime 3.0.0-alpha.6 → 3.0.0-alpha.60

package/src/wml.js

@@ -0,0 +1,250 @@
+/*
+ _     __     _ __
+| |  / /___ _(_) /____
+| | /| / / __ `/ / / ___/
+| |/ |/ / /_/ / / (__  )
+|__/|__/\__,_/_/_/____/
+The electron alternative for Go
+(c) Lea Anthony 2019-present
+*/
+
+import {OpenURL} from "./browser";
+import {Question} from "./dialogs";
+import {Emit, WailsEvent} from "./events";
+import {canAbortListeners, whenReady} from "./utils";
+import Window from "./window";
+
+/**
+ * Sends an event with the given name and optional data.
+ *
+ * @param {string} eventName - The name of the event to send.
+ * @param {any} [data=null] - Optional data to send along with the event.
+ *
+ * @return {void}
+ */
+function sendEvent(eventName, data=null) {
+    Emit(new WailsEvent(eventName, data));
+}
+
+/**
+ * Calls a method on a specified window.
+ * @param {string} windowName - The name of the window to call the method on.
+ * @param {string} methodName - The name of the method to call.
+ */
+function callWindowMethod(windowName, methodName) {
+    const targetWindow = Window.Get(windowName);
+    const method = targetWindow[methodName];
+
+    if (typeof method !== "function") {
+        console.error(`Window method '${methodName}' not found`);
+        return;
+    }
+
+    try {
+        method.call(targetWindow);
+    } catch (e) {
+        console.error(`Error calling window method '${methodName}': `, e);
+    }
+}
+
+/**
+ * Responds to a triggering event by running appropriate WML actions for the current target
+ *
+ * @param {Event} ev
+ * @return {void}
+ */
+function onWMLTriggered(ev) {
+    const element = ev.currentTarget;
+
+    function runEffect(choice = "Yes") {
+        if (choice !== "Yes")
+            return;
+
+        const eventType = element.getAttribute('data-wml-event');
+        const targetWindow = element.getAttribute('data-wml-target-window') || "";
+        const windowMethod = element.getAttribute('data-wml-window');
+        const url = element.getAttribute('data-wml-openURL');
+
+        if (eventType !== null)
+            sendEvent(eventType);
+        if (windowMethod !== null)
+            callWindowMethod(targetWindow, windowMethod);
+        if (url !== null)
+            void OpenURL(url);
+    }
+
+    const confirm = element.getAttribute('data-wml-confirm');
+
+    if (confirm) {
+        Question({
+            Title: "Confirm",
+            Message: confirm,
+            Detached: false,
+            Buttons: [
+                { Label: "Yes" },
+                { Label: "No", IsDefault: true }
+            ]
+        }).then(runEffect);
+    } else {
+        runEffect();
+    }
+}
+
+/**
+ * @type {symbol}
+ */
+const controller = Symbol();
+
+/**
+ * AbortControllerRegistry does not actually remember active event listeners: instead
+ * it ties them to an AbortSignal and uses an AbortController to remove them all at once.
+ */
+class AbortControllerRegistry {
+    constructor() {
+        /**
+         * Stores the AbortController that can be used to remove all currently active listeners.
+         *
+         * @private
+         * @name {@link controller}
+         * @member {AbortController}
+         */
+        this[controller] = new AbortController();
+    }
+
+    /**
+     * Returns an options object for addEventListener that ties the listener
+     * to the AbortSignal from the current AbortController.
+     *
+     * @param {HTMLElement} element An HTML element
+     * @param {string[]} triggers The list of active WML trigger events for the specified elements
+     * @returns {AddEventListenerOptions}
+     */
+    set(element, triggers) {
+        return { signal: this[controller].signal };
+    }
+
+    /**
+     * Removes all registered event listeners.
+     *
+     * @returns {void}
+     */
+    reset() {
+        this[controller].abort();
+        this[controller] = new AbortController();
+    }
+}
+
+/**
+ * @type {symbol}
+ */
+const triggerMap = Symbol();
+
+/**
+ * @type {symbol}
+ */
+const elementCount = Symbol();
+
+/**
+ * WeakMapRegistry maps active trigger events to each DOM element through a WeakMap.
+ * This ensures that the mapping remains private to this module, while still allowing garbage
+ * collection of the involved elements.
+ */
+class WeakMapRegistry {
+    constructor() {
+        /**
+         * Stores the current element-to-trigger mapping.
+         *
+         * @private
+         * @name {@link triggerMap}
+         * @member {WeakMap<HTMLElement, string[]>}
+         */
+        this[triggerMap] = new WeakMap();
+
+        /**
+         * Counts the number of elements with active WML triggers.
+         *
+         * @private
+         * @name {@link elementCount}
+         * @member {number}
+         */
+        this[elementCount] = 0;
+    }
+
+    /**
+     * Sets the active triggers for the specified element.
+     *
+     * @param {HTMLElement} element An HTML element
+     * @param {string[]} triggers The list of active WML trigger events for the specified element
+     * @returns {AddEventListenerOptions}
+     */
+    set(element, triggers) {
+        this[elementCount] += !this[triggerMap].has(element);
+        this[triggerMap].set(element, triggers);
+        return {};
+    }
+
+    /**
+     * Removes all registered event listeners.
+     *
+     * @returns {void}
+     */
+    reset() {
+        if (this[elementCount] <= 0)
+            return;
+
+        for (const element of document.body.querySelectorAll('*')) {
+            if (this[elementCount] <= 0)
+                break;
+
+            const triggers = this[triggerMap].get(element);
+            this[elementCount] -= (typeof triggers !== "undefined");
+
+            for (const trigger of triggers || [])
+                element.removeEventListener(trigger, onWMLTriggered);
+        }
+
+        this[triggerMap] = new WeakMap();
+        this[elementCount] = 0;
+    }
+}
+
+const triggerRegistry = canAbortListeners() ? new AbortControllerRegistry() : new WeakMapRegistry();
+
+/**
+ * Adds event listeners to the specified element.
+ *
+ * @param {HTMLElement} element
+ * @return {void}
+ */
+function addWMLListeners(element) {
+    const triggerRegExp = /\S+/g;
+    const triggerAttr = (element.getAttribute('data-wml-trigger') || "click");
+    const triggers = [];
+
+    let match;
+    while ((match = triggerRegExp.exec(triggerAttr)) !== null)
+        triggers.push(match[0]);
+
+    const options = triggerRegistry.set(element, triggers);
+    for (const trigger of triggers)
+        element.addEventListener(trigger, onWMLTriggered, options);
+}
+
+/**
+ * Schedules an automatic reload of WML to be performed as soon as the document is fully loaded.
+ *
+ * @return {void}
+ */
+export function Enable() {
+    whenReady(Reload);
+}
+
+/**
+ * Reloads the WML page by adding necessary event listeners and browser listeners.
+ *
+ * @return {void}
+ */
+export function Reload() {
+    triggerRegistry.reset();
+    document.body.querySelectorAll('[data-wml-event], [data-wml-window], [data-wml-openURL]').forEach(addWMLListeners);
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "include": ["./src/**/*"],
+  "compilerOptions": {
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "strict": true,
+    "target": "es6",
+  }
+}

package/types/application.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hides a certain method by calling the HideMethod function.
+ *
+ * @return {Promise<void>}
+ *
+ */
+export function Hide(): Promise<void>;
+/**
+ * Calls the ShowMethod and returns the result.
+ *
+ * @return {Promise<void>}
+ */
+export function Show(): Promise<void>;
+/**
+ * Calls the QuitMethod to terminate the program.
+ *
+ * @return {Promise<void>}
+ */
+export function Quit(): Promise<void>;

package/types/browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Open a browser window to the given URL
+ * @param {string} url - The URL to open
+ * @returns {Promise<string>}
+ */
+export function OpenURL(url: string): Promise<string>;

package/types/calls.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Call a bound method according to the given call options.
+ *
+ * In case of failure, the returned promise will reject with an exception
+ * among ReferenceError (unknown method), TypeError (wrong argument count or type),
+ * {@link RuntimeError} (method returned an error), or other (network or internal errors).
+ * The exception might have a "cause" field with the value returned
+ * by the application- or service-level error marshaling functions.
+ *
+ * @param {CallOptions} options - A method call descriptor.
+ * @returns {Promise<any>} - The result of the call.
+ */
+export function Call(options: CallOptions): Promise<any>;
+/**
+ * Calls a bound method by name with the specified arguments.
+ * See {@link Call} for details.
+ *
+ * @param {string} methodName - The name of the method in the format 'package.struct.method'.
+ * @param {any[]} args - The arguments to pass to the method.
+ * @returns {Promise<any>} The result of the method call.
+ */
+export function ByName(methodName: string, ...args: any[]): Promise<any>;
+/**
+ * Calls a method by its numeric ID with the specified arguments.
+ * See {@link Call} for details.
+ *
+ * @param {number} methodID - The ID of the method to call.
+ * @param {any[]} args - The arguments to pass to the method.
+ * @return {Promise<any>} - The result of the method call.
+ */
+export function ByID(methodID: number, ...args: any[]): Promise<any>;
+/**
+ * Collects all required information for a binding call.
+ *
+ * @typedef {Object} CallOptions
+ * @property {number} [methodID] - The numeric ID of the bound method to call.
+ * @property {string} [methodName] - The fully qualified name of the bound method to call.
+ * @property {any[]} args - Arguments to be passed into the bound method.
+ */
+/**
+ * Exception class that will be thrown in case the bound method returns an error.
+ * The value of the {@link RuntimeError#name} property is "RuntimeError".
+ */
+export class RuntimeError extends Error {
+    /**
+     * Constructs a new RuntimeError instance.
+     *
+     * @param {string} message - The error message.
+     * @param {any[]} args - Optional arguments for the Error constructor.
+     */
+    constructor(message: string, ...args: any[]);
+}
+/**
+ * Collects all required information for a binding call.
+ */
+export type CallOptions = {
+    /**
+     * - The numeric ID of the bound method to call.
+     */
+    methodID?: number;
+    /**
+     * - The fully qualified name of the bound method to call.
+     */
+    methodName?: string;
+    /**
+     * - Arguments to be passed into the bound method.
+     */
+    args: any[];
+};

package/types/clipboard.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sets the text to the Clipboard.
+ *
+ * @param {string} text - The text to be set to the Clipboard.
+ * @return {Promise} - A Promise that resolves when the operation is successful.
+ */
+export function SetText(text: string): Promise<any>;
+/**
+ * Get the Clipboard text
+ * @returns {Promise<string>} A promise that resolves with the text from the Clipboard.
+ */
+export function Text(): Promise<string>;

package/types/create.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Any is a dummy creation function for simple or unknown types.
+ * @template T
+ * @param {any} source
+ * @returns {T}
+ */
+export function Any<T>(source: any): T;
+/**
+ * ByteSlice is a creation function that replaces
+ * null strings with empty strings.
+ * @param {any} source
+ * @returns {string}
+ */
+export function ByteSlice(source: any): string;
+/**
+ * Array takes a creation function for an arbitrary type
+ * and returns an in-place creation function for an array
+ * whose elements are of that type.
+ * @template T
+ * @param {(source: any) => T} element
+ * @returns {(source: any) => T[]}
+ */
+export function Array<T>(element: (source: any) => T): (source: any) => T[];
+/**
+ * Map takes creation functions for two arbitrary types
+ * and returns an in-place creation function for an object
+ * whose keys and values are of those types.
+ * @template K, V
+ * @param {(source: any) => K} key
+ * @param {(source: any) => V} value
+ * @returns {(source: any) => { [_: K]: V }}
+ */
+export function Map<K, V>(key: (source: any) => K, value: (source: any) => V): (source: any) => {};
+/**
+ * Nullable takes a creation function for an arbitrary type
+ * and returns a creation function for a nullable value of that type.
+ * @template T
+ * @param {(source: any) => T} element
+ * @returns {(source: any) => (T | null)}
+ */
+export function Nullable<T>(element: (source: any) => T): (source: any) => T;
+/**
+ * Struct takes an object mapping field names to creation functions
+ * and returns an in-place creation function for a struct.
+ * @template {{ [_: string]: ((source: any) => any) }} T
+ * @template {{ [Key in keyof T]?: ReturnType<T[Key]> }} U
+ * @param {T} createField
+ * @returns {(source: any) => U}
+ */
+export function Struct<T extends {
+    [_: string]: (source: any) => any;
+}, U extends { [Key in keyof T]?: ReturnType<T[Key]>; }>(createField: T): (source: any) => U;

package/types/dialogs.d.ts

@@ -0,0 +1,184 @@
+export function Info(options: MessageDialogOptions): Promise<string>;
+export function Warning(options: MessageDialogOptions): Promise<string>;
+export function Error(options: MessageDialogOptions): Promise<string>;
+export function Question(options: MessageDialogOptions): Promise<string>;
+export function OpenFile(options: OpenFileDialogOptions): Promise<string[] | string>;
+export function SaveFile(options: SaveFileDialogOptions): Promise<string>;
+export type OpenFileDialogOptions = {
+    /**
+     * - Indicates if directories can be chosen.
+     */
+    CanChooseDirectories?: boolean;
+    /**
+     * - Indicates if files can be chosen.
+     */
+    CanChooseFiles?: boolean;
+    /**
+     * - Indicates if directories can be created.
+     */
+    CanCreateDirectories?: boolean;
+    /**
+     * - Indicates if hidden files should be shown.
+     */
+    ShowHiddenFiles?: boolean;
+    /**
+     * - Indicates if aliases should be resolved.
+     */
+    ResolvesAliases?: boolean;
+    /**
+     * - Indicates if multiple selection is allowed.
+     */
+    AllowsMultipleSelection?: boolean;
+    /**
+     * - Indicates if the extension should be hidden.
+     */
+    HideExtension?: boolean;
+    /**
+     * - Indicates if hidden extensions can be selected.
+     */
+    CanSelectHiddenExtension?: boolean;
+    /**
+     * - Indicates if file packages should be treated as directories.
+     */
+    TreatsFilePackagesAsDirectories?: boolean;
+    /**
+     * - Indicates if other file types are allowed.
+     */
+    AllowsOtherFiletypes?: boolean;
+    /**
+     * - Array of file filters.
+     */
+    Filters?: FileFilter[];
+    /**
+     * - Title of the dialog.
+     */
+    Title?: string;
+    /**
+     * - Message to show in the dialog.
+     */
+    Message?: string;
+    /**
+     * - Text to display on the button.
+     */
+    ButtonText?: string;
+    /**
+     * - Directory to open in the dialog.
+     */
+    Directory?: string;
+    /**
+     * - Indicates if the dialog should appear detached from the main window.
+     */
+    Detached?: boolean;
+};
+export type SaveFileDialogOptions = {
+    /**
+     * - Default filename to use in the dialog.
+     */
+    Filename?: string;
+    /**
+     * - Indicates if directories can be chosen.
+     */
+    CanChooseDirectories?: boolean;
+    /**
+     * - Indicates if files can be chosen.
+     */
+    CanChooseFiles?: boolean;
+    /**
+     * - Indicates if directories can be created.
+     */
+    CanCreateDirectories?: boolean;
+    /**
+     * - Indicates if hidden files should be shown.
+     */
+    ShowHiddenFiles?: boolean;
+    /**
+     * - Indicates if aliases should be resolved.
+     */
+    ResolvesAliases?: boolean;
+    /**
+     * - Indicates if multiple selection is allowed.
+     */
+    AllowsMultipleSelection?: boolean;
+    /**
+     * - Indicates if the extension should be hidden.
+     */
+    HideExtension?: boolean;
+    /**
+     * - Indicates if hidden extensions can be selected.
+     */
+    CanSelectHiddenExtension?: boolean;
+    /**
+     * - Indicates if file packages should be treated as directories.
+     */
+    TreatsFilePackagesAsDirectories?: boolean;
+    /**
+     * - Indicates if other file types are allowed.
+     */
+    AllowsOtherFiletypes?: boolean;
+    /**
+     * - Array of file filters.
+     */
+    Filters?: FileFilter[];
+    /**
+     * - Title of the dialog.
+     */
+    Title?: string;
+    /**
+     * - Message to show in the dialog.
+     */
+    Message?: string;
+    /**
+     * - Text to display on the button.
+     */
+    ButtonText?: string;
+    /**
+     * - Directory to open in the dialog.
+     */
+    Directory?: string;
+    /**
+     * - Indicates if the dialog should appear detached from the main window.
+     */
+    Detached?: boolean;
+};
+export type MessageDialogOptions = {
+    /**
+     * - The title of the dialog window.
+     */
+    Title?: string;
+    /**
+     * - The main message to show in the dialog.
+     */
+    Message?: string;
+    /**
+     * - Array of button options to show in the dialog.
+     */
+    Buttons?: Button[];
+    /**
+     * - True if the dialog should appear detached from the main window (if applicable).
+     */
+    Detached?: boolean;
+};
+export type Button = {
+    /**
+     * - Text that appears within the button.
+     */
+    Label?: string;
+    /**
+     * - True if the button should cancel an operation when clicked.
+     */
+    IsCancel?: boolean;
+    /**
+     * - True if the button should be the default action when the user presses enter.
+     */
+    IsDefault?: boolean;
+};
+export type FileFilter = {
+    /**
+     * - Display name for the filter, it could be "Text Files", "Images" etc.
+     */
+    DisplayName?: string;
+    /**
+     * - Pattern to match for the filter, e.g. "*.txt;*.md" for text markdown files.
+     */
+    Pattern?: string;
+};