@siliconst/metaui 1.4.44 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/controls/GeolocationControl.ts

@@ -1,90 +1,267 @@
-/**
- * @file GeolocationControl.ts
- * @description Native UI5 Control for GPS capture.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.controls
- */
-import BaseHardwareControl from "./BaseHardwareControl";
-import BaseHardwareControlRenderer from "./BaseHardwareControlRenderer";
-import RenderManager from "sap/ui/core/RenderManager";
-import Button from "sap/m/Button";
-import Input from "sap/m/Input";
-import VBox from "sap/m/VBox";
-import MessageToast from "sap/m/MessageToast";
-
-export default class GeolocationControl extends BaseHardwareControl {
-    private vBox!: VBox;
-    private locationBtn!: Button;
-    private resultInput!: Input;
-
-    static readonly renderer = BaseHardwareControlRenderer;
-
-    /**
-     * Initializes the control and builds the internal UI components.
-     */
-    public init(): void {
-        super.init();
-
-        this.locationBtn = new Button({
-            icon: "sap-icon://map",
-            text: "Get Location",
-            press: this.getLocation.bind(this)
-        });
-
-        this.resultInput = new Input({
-            editable: false,
-            visible: false
-        });
-
-        this.vBox = new VBox({
-            items: [this.locationBtn, this.resultInput]
-        });
-
-        this.setAggregation("_content", this.vBox);
-    }
-
-    /**
-     * Lifecycle hook called before the control is rendered to the DOM.
-     * Updates button state and sets any existing values.
-     */
-    public onBeforeRendering(): void {
-        const metadata = this.getProperty("schemaMetadata");
-        if (metadata && metadata.ui && metadata.ui.label) {
-            this.locationBtn.setText(metadata.ui.label);
-        }
-
-        const readOnly = this.getProperty("readOnly");
-        this.locationBtn.setEnabled(!readOnly);
-
-        const currentVal = this.getProperty("value");
-        if (currentVal) {
-            this.resultInput.setValue(currentVal as string);
-            this.resultInput.setVisible(true);
-        }
-    }
-
-    private getLocation(): void {
-        if (!navigator.geolocation) {
-            MessageToast.show("Geolocation is not supported by your browser");
-            return;
-        }
-
-        navigator.geolocation.getCurrentPosition(
-            (position) => {
-                const locStr = `${position.coords.latitude}, ${position.coords.longitude}`;
-                this.resultInput.setValue(locStr);
-                this.resultInput.setVisible(true);
-                this.setValueAndFire(locStr);
-                MessageToast.show("Location acquired.");
-            },
-            (error) => {
-                import("../utils/Logger").then(({ Logger }) => {
-                    Logger.error("[MetaUI] Geolocation failed or denied", error.message, "GeolocationControl");
-                });
-                MessageToast.show("Unable to retrieve your location");
-            }
-        );
-    }
-
-
-}
+/**
+ * @file GeolocationControl.ts
+ * @description Hardware control for acquiring GPS coordinates via the browser Geolocation API (navigator.geolocation).
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.controls
+ */
+import BaseHardwareControl, { $BaseHardwareControlSettings, HardwareFailureReason } from "./BaseHardwareControl";
+import BaseHardwareControlRenderer from "./BaseHardwareControlRenderer";
+import HBox from "sap/m/HBox";
+import Input from "sap/m/Input";
+import Button from "sap/m/Button";
+import FlexItemData from "sap/m/FlexItemData";
+import { ButtonType, FlexAlignItems } from "sap/m/library";
+import { isRecord } from "../utils/TypeGuards";
+import { I18n, TEXT_KEY } from "../utils/I18n";
+
+/**
+ * Custom UI5 control that captures `{ lat, lng }` coordinates using `navigator.geolocation.getCurrentPosition`.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.controls
+ * @internal
+ */
+export default class GeolocationControl extends BaseHardwareControl {
+    static renderer = BaseHardwareControlRenderer;
+
+    /** Device name used in the user-visible message when a position cannot be obtained. */
+    private static readonly CAPABILITY_NAME = "Location";
+
+    /**
+     * Milliseconds the browser is allowed to spend producing a fix.
+     *
+     * `getCurrentPosition` was previously called with no options object at all, so `timeout` took its
+     * specified default of `0xFFFFFFFF` ms — roughly 50 days (W3C Geolocation API, §7 `PositionOptions`) —
+     * and a request that never completed left the button spinning for the lifetime of the page.
+     *
+     * With `enableHighAccuracy` off the browser answers from its network location provider rather than
+     * waiting for a GNSS fix, which resolves in well under two seconds on every engine measured, so ten
+     * seconds is an order of magnitude of headroom and still inside the window where a person associates
+     * the message with the button they pressed.
+     */
+    private static readonly POSITION_TIMEOUT_MS = 10000;
+
+    /**
+     * Extra milliseconds the control waits beyond {@link GeolocationControl.POSITION_TIMEOUT_MS} before
+     * giving up on its own.
+     *
+     * The W3C Geolocation API states in §7.2 that "the time spent waiting for the document to become
+     * visible and for obtaining permission to use the API is not included in the period covered by the
+     * timeout member", and that the member "only applies when acquiring a position begins". A permission
+     * prompt that is dismissed rather than answered therefore starts no browser timer at all and invokes
+     * neither callback — Firefox's behaviour, reproduced with the spinner still running at ten seconds.
+     * This watchdog is the only thing that can end that state. The grace period lets the browser's own
+     * `TIMEOUT` error win whenever a browser timer *is* running, so the watchdog only ever fires for the
+     * case the specification deliberately leaves uncovered.
+     */
+    private static readonly WATCHDOG_GRACE_MS = 2000;
+
+    private coordInput!: Input;
+    private locateBtn!: Button;
+    private watchdogId: number | null = null;
+
+    constructor(idOrSettings?: string | $BaseHardwareControlSettings, settings?: $BaseHardwareControlSettings) {
+        super(idOrSettings, settings);
+    }
+
+    /**
+     * Initializes the internal HBox layout containing the read-only coordinate display `Input` and Locate `Button`.
+     */
+    public init(): void {
+        if (BaseHardwareControl.prototype.init) {
+            BaseHardwareControl.prototype.init.call(this);
+        }
+
+        this.coordInput = new Input({
+            editable: false,
+            placeholder: I18n.getText(TEXT_KEY.geolocationPlaceholder),
+            width: "100%",
+            layoutData: new FlexItemData({ growFactor: 1 })
+        }).addStyleClass("sapUiTinyMarginEnd");
+
+        this.locateBtn = new Button({
+            text: I18n.getText(TEXT_KEY.geolocationGetLocation),
+            icon: "sap-icon://locate-me",
+            type: ButtonType.Emphasized,
+            press: () => {
+                this.acquireLocation();
+            }
+        });
+
+        const layout = new HBox({
+            width: "100%",
+            alignItems: FlexAlignItems.Center,
+            items: [this.coordInput, this.locateBtn]
+        });
+
+        this.setAggregation("_content", layout);
+    }
+
+    /**
+     * Synchronizes the Locate button's `enabled` state and coordinate display before rendering.
+     */
+    public onBeforeRendering(): void {
+        this.syncHardwareState();
+        this.updateDisplayFromValue(this.getProperty("value"));
+    }
+
+    /**
+     * Synchronizes the inner coordinate `Input` and Locate `Button` with `readOnly`, `valueState`, and `valueStateText`.
+     */
+    protected override syncHardwareState(): void {
+        if (this.locateBtn) {
+            this.locateBtn.setEnabled(!this.getProperty("readOnly"));
+        }
+        if (this.coordInput) {
+            this.coordInput.setValueState(this.getValueState());
+            this.coordInput.setValueStateText(this.getValueStateText());
+        }
+    }
+
+    /**
+     * Updates the `value` property (`{ lat, lng }` or string) and refreshes the coordinate text field.
+     *
+     * @param vValue The new geolocation value.
+     * @returns {this} This control instance for chaining.
+     */
+    public setValue(vValue: unknown): this {
+        this.setProperty("value", vValue, true);
+        this.updateDisplayFromValue(vValue);
+        return this;
+    }
+
+    /**
+     * Formats the stored coordinate value (`{ lat, lng }` object or string) into the display `Input`.
+     *
+     * @param vValue The coordinate value to format.
+     */
+    private updateDisplayFromValue(vValue: unknown): void {
+        if (!this.coordInput) {
+            return;
+        }
+        let formatted = "";
+        if (isRecord(vValue) && vValue.lat !== undefined && vValue.lng !== undefined) {
+            formatted = `${vValue.lat}, ${vValue.lng}`;
+        } else if (typeof vValue === "string") {
+            formatted = vValue;
+        }
+        if (this.coordInput.getValue() !== formatted) {
+            this.coordInput.setValue(formatted);
+        }
+    }
+
+    /**
+     * Requests the current position from `navigator.geolocation` and stores `{ lat, lng }` in `value`.
+     *
+     * Every exit path — success, browser error, and the watchdog that covers the case where the browser
+     * calls neither callback — clears the button's busy state exactly once.
+     */
+    private acquireLocation(): void {
+        if (this.getProperty("readOnly")) {
+            return;
+        }
+        if (!navigator.geolocation) {
+            this.reportCapabilityFailure(GeolocationControl.CAPABILITY_NAME, "unsupported");
+            return;
+        }
+
+        this.cancelWatchdog();
+        this.locateBtn.setBusy(true);
+
+        let settled = false;
+        const settle = (): boolean => {
+            if (settled || this.isDestroyed()) {
+                return false;
+            }
+            settled = true;
+            this.cancelWatchdog();
+            this.locateBtn.setBusy(false);
+            return true;
+        };
+
+        const watchdogMs = GeolocationControl.POSITION_TIMEOUT_MS + GeolocationControl.WATCHDOG_GRACE_MS;
+        this.watchdogId = window.setTimeout(() => {
+            this.watchdogId = null;
+            if (!settle()) {
+                return;
+            }
+            this.reportCapabilityFailure(
+                GeolocationControl.CAPABILITY_NAME,
+                "timeout",
+                `neither callback ran within ${watchdogMs} ms; the permission prompt was most likely dismissed`
+            );
+        }, watchdogMs);
+
+        try {
+            navigator.geolocation.getCurrentPosition(
+                (pos: GeolocationPosition) => {
+                    if (!settle()) {
+                        return;
+                    }
+                    this.clearCapabilityFailure();
+                    const coordsObj = {
+                        lat: Number(pos.coords.latitude.toFixed(6)),
+                        lng: Number(pos.coords.longitude.toFixed(6))
+                    };
+                    this.setValue(coordsObj);
+                    this.fireEvent("capture", { value: coordsObj });
+                },
+                (err: GeolocationPositionError) => {
+                    if (!settle()) {
+                        return;
+                    }
+                    this.reportCapabilityFailure(
+                        GeolocationControl.CAPABILITY_NAME,
+                        GeolocationControl.classifyPositionError(err),
+                        `code ${err.code}: ${err.message}`
+                    );
+                },
+                {
+                    enableHighAccuracy: false,
+                    timeout: GeolocationControl.POSITION_TIMEOUT_MS,
+                    maximumAge: 0
+                }
+            );
+        } catch (err) {
+            // A synchronous throw — an insecure origin on some engines, or a stubbed-out API — is an
+            // exit path too, and the one that would otherwise leave the spinner up until the watchdog.
+            if (settle()) {
+                this.reportCapabilityFailure(GeolocationControl.CAPABILITY_NAME, "failed", (err as Error).message);
+            }
+        }
+    }
+
+    /**
+     * Maps a `GeolocationPositionError` code onto the shared hardware failure vocabulary.
+     *
+     * @param err The error handed to the `getCurrentPosition` error callback.
+     * @returns {HardwareFailureReason} The reason reported to the user and the log.
+     */
+    private static classifyPositionError(err: GeolocationPositionError): HardwareFailureReason {
+        switch (err.code) {
+            case 1: // PERMISSION_DENIED
+                return "denied";
+            case 3: // TIMEOUT
+                return "timeout";
+            default: // POSITION_UNAVAILABLE (2) and anything a browser invents
+                return "failed";
+        }
+    }
+
+    /**
+     * Stops the pending watchdog timer, if any.
+     */
+    private cancelWatchdog(): void {
+        if (this.watchdogId !== null) {
+            window.clearTimeout(this.watchdogId);
+            this.watchdogId = null;
+        }
+    }
+
+    /**
+     * Cancels any pending watchdog timer when the control is destroyed, so a torn-down control
+     * cannot be woken by its own timer.
+     */
+    public exit(): void {
+        this.cancelWatchdog();
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/controls/RichTextControl.ts

@@ -1,75 +1,199 @@
-import BaseHardwareControl from "./BaseHardwareControl";
-import BaseHardwareControlRenderer from "./BaseHardwareControlRenderer";
-import RenderManager from "sap/ui/core/RenderManager";
-import VBox from "sap/m/VBox";
-import RichTextEditor from "sap/ui/richtexteditor/RichTextEditor";
-
-import Event from "sap/ui/base/Event";
-/**
- * @file RichTextControl.ts
- * @description Native UI5 Control for rich text input.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.controls
- */
-export default class RichTextControl extends BaseHardwareControl {
-    private vBox!: VBox;
-    private richTextEditor!: RichTextEditor;
-
-    static readonly renderer = BaseHardwareControlRenderer;
-
-    public init(): void {
-        super.init();
-
-        this.richTextEditor = new RichTextEditor({
-            width: "100%",
-            height: "300px",
-            showGroupFont: true,
-            showGroupInsert: true,
-            tooltip: "Rich Text Editor",
-            change: (oEvent: Event) => {
-                const val = oEvent.getParameter("newValue");
-                this.setValueAndFire(val);
-            }
-        });
-
-        this.vBox = new VBox({
-            items: [this.richTextEditor]
-        });
-
-        this.setAggregation("_content", this.vBox);
-    }
-
-    public onBeforeRendering(): void {
-        const readOnly = this.getProperty("readOnly");
-        this.richTextEditor.setEditable(!readOnly);
-
-        const currentVal = this.getProperty("value");
-        if (currentVal !== undefined && currentVal !== null) {
-            // Prevent recursive update if the value matches the editor's current value
-            if (this.richTextEditor.getValue() !== currentVal) {
-                this.richTextEditor.setValue(currentVal as string);
-            }
-        }
-    }
-
-    /**
-     * Overrides the default property setter to prevent full DOM invalidation.
-     * When dataJson pushes updates down to the UI5 models, UI5 typically destroys 
-     * and recreates the custom control if the property changes. 
-     * By suppressing re-rendering (true flag) and manually passing the value 
-     * to the inner RichTextEditor, we prevent TinyMCE from tearing down its iframe
-     * and triggering expensive, redundant plugin boot sequences.
-     *
-     * @param {unknown} val The new string value to bind
-     * @returns {this} The control instance for chaining
-     */
-    public setValue(val: unknown): this {
-        this.setProperty("value", val, true); // suppress re-rendering
-        if (this.richTextEditor && val !== undefined && val !== null) {
-            if (this.richTextEditor.getValue() !== val) {
-                this.richTextEditor.setValue(val as string);
-            }
-        }
-        return this;
-    }
-}
+/**
+ * @file RichTextControl.ts
+ * @description Custom UI5 control wrapping sap.ui.richtexteditor.RichTextEditor with fallback to sap.m.TextArea.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.controls
+ */
+import BaseHardwareControl, { $BaseHardwareControlSettings } from "./BaseHardwareControl";
+import BaseHardwareControlRenderer from "./BaseHardwareControlRenderer";
+import VBox from "sap/m/VBox";
+import TextArea from "sap/m/TextArea";
+import Control from "sap/ui/core/Control";
+import Event from "sap/ui/base/Event";
+import RichTextEditor, {
+    RichTextEditor$ChangeEventParameters
+} from "sap/ui/richtexteditor/RichTextEditor";
+import { Logger } from "../utils/Logger";
+
+/**
+ * Custom UI5 control that lazily loads `sap.ui.richtexteditor.RichTextEditor` (or falls back to `sap.m.TextArea`
+ * when the `sap.ui.richtexteditor` library is not available) and emits `capture` on content changes.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.controls
+ * @internal
+ */
+export default class RichTextControl extends BaseHardwareControl {
+    static renderer = BaseHardwareControlRenderer;
+    private editorControl: Control | null = null;
+    private container!: VBox;
+
+    constructor(idOrSettings?: string | $BaseHardwareControlSettings, settings?: $BaseHardwareControlSettings) {
+        super(idOrSettings, settings);
+    }
+
+    /**
+     * Initializes the internal VBox container with a synchronous TextArea editor and upgrades to
+     * `sap.ui.richtexteditor.RichTextEditor` when the library is loaded in the UI5 environment.
+     */
+    public init(): void {
+        if (BaseHardwareControl.prototype.init) {
+            BaseHardwareControl.prototype.init.call(this);
+        }
+
+        this.container = new VBox({
+            width: "100%"
+        });
+
+        this.setAggregation("_content", this.container);
+        this.mountFallbackTextArea();
+        this.instantiateEditor();
+    }
+
+    /**
+     * Sanitizes raw HTML strings in fallback mode by stripping `<script>` blocks, inline `on*` event attributes,
+     * and `javascript:` protocol URIs.
+     *
+     * @param raw The raw HTML string.
+     * @returns {string} The sanitized HTML string.
+     */
+    private static sanitizeHtml(raw: string): string {
+        if (!raw) {
+            return "";
+        }
+        return raw
+            .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "")
+            .replace(/\bon[a-z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "")
+            .replace(/javascript\s*:/gi, "");
+    }
+
+    /**
+     * Mounts a synchronous `sap.m.TextArea` editor so the control immediately renders with non-zero
+     * geometry and interactive editing before or without `sap.ui.richtexteditor`.
+     */
+    private mountFallbackTextArea(): void {
+        const currentVal = RichTextControl.sanitizeHtml((this.getProperty("value") as string) || "");
+        const isReadOnly = Boolean(this.getProperty("readOnly"));
+        const fallbackTa = new TextArea({
+            width: "100%",
+            rows: 6,
+            value: currentVal,
+            editable: !isReadOnly,
+            valueState: this.getValueState(),
+            valueStateText: this.getValueStateText(),
+            change: () => {
+                const newVal = RichTextControl.sanitizeHtml(fallbackTa.getValue());
+                if (fallbackTa.getValue() !== newVal) {
+                    fallbackTa.setValue(newVal);
+                }
+                this.setProperty("value", newVal, true);
+                this.fireEvent("capture", { value: newVal });
+            }
+        });
+        this.editorControl = fallbackTa;
+        this.container.destroyItems();
+        this.container.addItem(fallbackTa);
+    }
+
+    /**
+     * Upgrades to `sap/ui/richtexteditor/RichTextEditor` when the library is registered in the UI5 core.
+     */
+    private instantiateEditor(): void {
+        const loadedLibs = sap.ui.getCore().getLoadedLibraries?.() || {};
+        if (!loadedLibs["sap.ui.richtexteditor"]) {
+            return;
+        }
+        sap.ui.require(
+            ["sap/ui/richtexteditor/RichTextEditor"],
+            (RichTextEditorClass: typeof RichTextEditor) => {
+                if (this.isDestroyed()) {
+                    return;
+                }
+                const currentVal = (this.getProperty("value") as string) || "";
+                const isReadOnly = Boolean(this.getProperty("readOnly"));
+
+                const rte = new RichTextEditorClass({
+                    width: "100%",
+                    height: "250px",
+                    value: currentVal,
+                    editable: !isReadOnly,
+                    showGroupFont: true,
+                    showGroupInsert: true,
+                    change: (oEvent: Event<RichTextEditor$ChangeEventParameters>) => {
+                        const newVal = oEvent.getParameters()?.newValue ?? rte.getValue();
+                        this.setProperty("value", newVal, true);
+                        this.fireEvent("capture", { value: newVal });
+                    }
+                });
+
+                this.editorControl = rte;
+                this.container.destroyItems();
+                this.container.addItem(rte);
+            },
+            () => {
+                Logger.debug("sap.ui.richtexteditor not available; keeping sap.m.TextArea.", undefined, "RichTextControl");
+            }
+        );
+    }
+
+    /**
+     * Synchronizes `value` and `editable` with the inner editor before rendering.
+     */
+    public onBeforeRendering(): void {
+        this.syncEditorState();
+    }
+
+    /**
+     * Synchronizes `readOnly`, `valueState`, and `valueStateText` with the active inner editor.
+     */
+    protected override syncHardwareState(): void {
+        this.syncEditorState();
+    }
+
+    /**
+     * Updates the `value` property and propagates it to the underlying editor instance.
+     *
+     * @param sValue The new HTML string value.
+     * @returns {this} This control instance for chaining.
+     */
+    public setValue(sValue: string | null): this {
+        const sanitized = sValue ? RichTextControl.sanitizeHtml(sValue) : sValue;
+        this.setProperty("value", sanitized, true);
+        this.syncEditorState();
+        return this;
+    }
+
+    /**
+     * Propagates the current `value` and `readOnly` state to the active inner editor (`RichTextEditor` or `TextArea`).
+     */
+    private syncEditorState(): void {
+        if (!this.editorControl) {
+            return;
+        }
+        const currentVal = RichTextControl.sanitizeHtml((this.getProperty("value") as string) || "");
+        const isReadOnly = Boolean(this.getProperty("readOnly"));
+
+        if (this.editorControl instanceof TextArea) {
+            if (this.editorControl.getValue() !== currentVal) {
+                this.editorControl.setValue(currentVal);
+            }
+            this.editorControl.setEditable(!isReadOnly);
+            this.editorControl.setValueState(this.getValueState());
+            this.editorControl.setValueStateText(this.getValueStateText());
+        } else {
+            const rte = this.editorControl as RichTextEditor;
+            if (typeof rte.getValue === "function" && typeof rte.setValue === "function" && rte.getValue() !== currentVal) {
+                rte.setValue(currentVal);
+            }
+            if (typeof rte.setEditable === "function") {
+                rte.setEditable(!isReadOnly);
+            }
+        }
+    }
+
+    /**
+     * Releases the active inner editor reference when the control is destroyed.
+     */
+    public exit(): void {
+        this.editorControl = null;
+    }
+}