@preference-sl/pref-viewer 2.18.0 → 3.0.0-beta.1

package/src/quick-look-action.js

@@ -0,0 +1,291 @@
+import I18n from "./localization/i18n.js";
+
+/**
+ * Owns the localized Quick Look link and serialized USDZ preparation for one viewer.
+ * Prepares content before a trusted tap so Safari can navigate natively within the user gesture.
+ * Revisions prevent stale exports from becoming usable. Unused Blob URLs are revoked immediately;
+ * handed-off URLs survive invalidation/detach until an observed native return or document unload.
+ * Call dispose() when the owning viewer is torn down.
+ */
+export default class QuickLookAction {
+    /**
+     * URL fragment appended to the prepared USDZ link; AR Quick Look parses it as viewer options.
+     * `allowsContentScaling=0` disables pinch scaling so the model keeps its authored real-world size.
+     * @public
+     * @static
+     * @type {string}
+     */
+    static QUICK_LOOK_FRAGMENT = "allowsContentScaling=0";
+
+    #anchor;
+    #style;
+    #window;
+    #urlAPI;
+    #canActivate;
+    #getCulture;
+    #revision = 0;
+    #disposed = false;
+    #exporter = null;
+    #work = Promise.resolve();
+    #url = null;
+    #handedOff = new Set();
+    #retired = new Set();
+    #away = false;
+    #unsubscribe;
+
+    /**
+     * Creates a hidden AR anchor and subscribes to locale and native-return lifecycle signals.
+     * @param {HTMLElement} container - Browser-owned canvas wrapper receiving the link and styles.
+     * @param {function(): boolean} [canActivate] - Host visibility/readiness gate; defaults to allowing activation.
+     * @param {function(): string} [getCulture] - Host locale provider; defaults to the active I18n locale.
+     */
+    constructor(container, canActivate = () => true, getCulture = () => I18n.getLocale()) {
+        const document = container.ownerDocument;
+        this.#window = document.defaultView;
+        this.#urlAPI = this.#window.URL;
+        this.#canActivate = canActivate;
+        this.#getCulture = getCulture;
+        this.#style = document.createElement("style");
+        this.#style.textContent = `
+            .pref-viewer-quick-look { position:absolute; right:20px; bottom:50px; z-index:11; display:block; cursor:pointer; }
+            .pref-viewer-quick-look[hidden] { display:none !important; }
+            .pref-viewer-quick-look[aria-disabled="true"] { opacity:0.5; cursor:wait; }
+            .pref-viewer-quick-look>img { width:100%; height:100%; opacity:0; }
+        `;
+        this.#anchor = document.createElement("a");
+        this.#anchor.className = "babylonVRicon pref-viewer-quick-look";
+        this.#anchor.rel = "ar";
+        this.#anchor.download = "model.usdz";
+        this.#anchor.setAttribute("role", "button");
+        this.#anchor.tabIndex = 0;
+        this.#anchor.hidden = true;
+        const image = document.createElement("img");
+        image.alt = "";
+        image.src = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='80' height='50'/%3E";
+        this.#anchor.append(image); // Safari requires a single img/picture child inside rel=ar.
+        this.#anchor.addEventListener("click", this.#onClick);
+        this.#anchor.addEventListener("keydown", this.#onKeyDown);
+        container.append(this.#style, this.#anchor);
+        this.#window.addEventListener("blur", this.#onAway);
+        this.#window.addEventListener("focus", this.#onReturn);
+        document.addEventListener("visibilitychange", this.#onVisibility);
+        this.#unsubscribe = I18n.onLocaleChange(() => this.#label());
+        this.#label();
+    }
+
+    /**
+     * Updates accessible text and tooltip for the current preparation, ready or retry state.
+     * @private
+     * @returns {void}
+     */
+    #label() {
+        const key = this.#anchor.dataset.state === "error" ? "retry"
+            : this.#url ? "open" : "preparing";
+        const text = I18n.translate(`prefViewer.ar.${key}`, { locale: this.#getCulture() });
+        this.#anchor.setAttribute("aria-label", text);
+        this.#anchor.title = text;
+    }
+
+    /**
+     * Allows synchronous native navigation only for current, prepared content and an eligible host.
+     * Blocks unavailable activation, retries failed preparation and retains handed-off URLs until return.
+     * @private
+     * @param {MouseEvent} event - Anchor activation, including keyboard-triggered clicks.
+     * @returns {void}
+     */
+    #onClick = (event) => {
+        if (this.#disposed || !this.#canActivate() || !this.#url) {
+            event.preventDefault();
+            if (!this.#disposed && this.#canActivate() && this.#anchor.dataset.state === "error") {
+                this.update(this.#exporter);
+            }
+            return;
+        }
+        // Leave native anchor navigation synchronous with the user's gesture.
+        // Keep its URL alive until native return is observed, even if the model changes meanwhile.
+        this.#handedOff.add(this.#url);
+    };
+
+    /**
+     * Maps Space and Enter to the same guarded anchor activation without a second default action.
+     * @private
+     * @param {KeyboardEvent} event - Key press received by the focusable AR action.
+     * @returns {void}
+     */
+    #onKeyDown = (event) => {
+        if (event.key === " " || event.key === "Enter") {
+            event.preventDefault();
+            this.#anchor.click();
+        }
+    };
+
+    /**
+     * Records a possible native handoff so a later visible return can release retired URLs.
+     * @private
+     * @returns {void}
+     */
+    #onAway = () => { this.#away = true; };
+    /**
+     * Routes document visibility changes through the same away/return URL-ownership handling.
+     * @private
+     * @returns {void}
+     */
+    #onVisibility = () => {
+        if (this.#anchor.ownerDocument.visibilityState === "hidden") {
+            this.#onAway();
+        } else {
+            this.#onReturn();
+        }
+    };
+    /**
+     * Releases retired handed-off URLs after an observed away/visible-return cycle.
+     * Removes deferred return listeners after disposal; a still-current URL remains owned by the link.
+     * @private
+     * @returns {void}
+     */
+    #onReturn = () => {
+        if (!this.#away || this.#anchor.ownerDocument.visibilityState === "hidden") {
+            return;
+        }
+        this.#away = false;
+        for (const url of this.#retired) {
+            this.#urlAPI.revokeObjectURL(url);
+        }
+        this.#retired.clear();
+        this.#handedOff.clear();
+        if (this.#disposed) {
+            this.#removeReturnListeners();
+        }
+    };
+
+    /**
+     * Detaches window/document return listeners once no retired native content needs them.
+     * @private
+     * @returns {void}
+     */
+    #removeReturnListeners() {
+        this.#window.removeEventListener("blur", this.#onAway);
+        this.#window.removeEventListener("focus", this.#onReturn);
+        this.#anchor.ownerDocument.removeEventListener("visibilitychange", this.#onVisibility);
+    }
+
+    /**
+     * Refreshes accessible text from the host locale while the action is alive.
+     * @public
+     * @returns {void}
+     */
+    refreshCulture() {
+        if (!this.#disposed) {
+            this.#label();
+        }
+    }
+
+    /**
+     * Hides the action, invalidates pending exports and releases or retires its prepared Blob URL.
+     * Handed-off content stays available for native opening; the exporter must be supplied again.
+     * @public
+     * @returns {void}
+     */
+    invalidate() {
+        this.#revision += 1;
+        this.#anchor.removeAttribute("href");
+        this.#anchor.hidden = true;
+        this.#anchor.setAttribute("aria-disabled", "true");
+        this.#anchor.setAttribute("aria-busy", "false");
+        if (this.#url) {
+            if (this.#handedOff.has(this.#url)) {
+                this.#retired.add(this.#url);
+            } else {
+                this.#urlAPI.revokeObjectURL(this.#url);
+            }
+        }
+        this.#url = null;
+        this.#exporter = null;
+    }
+
+    /**
+     * Queues current-model export and exposes only a nonempty ZIP-signature USDZ as a native link.
+     * Obsolete revisions are ignored. Export failures are logged and shown as a retry action;
+     * they do not reject the returned work promise or expose an older model's content.
+     * @public
+     * @param {?(function(): Promise<Uint8Array>)} exporter - Current-model serializer, or null to invalidate without preparation.
+     * @returns {Promise<void>} Resolves after this queued preparation settles or becomes obsolete.
+     */
+    update(exporter) {
+        if (this.#disposed) {
+            return Promise.resolve();
+        }
+        this.invalidate();
+        this.#exporter = exporter;
+        if (!exporter) {
+            return Promise.resolve();
+        }
+        const revision = this.#revision;
+        this.#anchor.hidden = false;
+        this.#anchor.dataset.state = "preparing";
+        this.#anchor.setAttribute("aria-busy", "true");
+        this.#label();
+        // Serialize exports per viewer, dropping obsolete queued revisions before work starts.
+        this.#work = this.#work.then(async () => {
+            if (this.#disposed || revision !== this.#revision) {
+                return;
+            }
+            try {
+                const bytes = await exporter();
+                if (this.#disposed || revision !== this.#revision) {
+                    return;
+                }
+                // USDZ is a ZIP archive; never expose empty, JSON or glTF results as native AR.
+                if (!(bytes instanceof Uint8Array) || bytes.length < 4 || bytes[0] !== 0x50 || bytes[1] !== 0x4b || bytes[2] !== 3 || bytes[3] !== 4) {
+                    throw new Error("PrefViewer: invalid USDZ export");
+                }
+                const blob = new this.#window.Blob([bytes], {
+                    type: "model/vnd.usdz+zip"
+                });
+                this.#url = this.#urlAPI.createObjectURL(blob);
+                // Quick Look reads the fragment: content scaling off keeps the authored 1:1 metre scale,
+                // matching the Android WebXR path. The bare URL is kept for revocation.
+                this.#anchor.href = `${this.#url}#${QuickLookAction.QUICK_LOOK_FRAGMENT}`;
+                this.#anchor.dataset.state = "ready";
+                this.#anchor.setAttribute("aria-disabled", "false");
+            } catch (error) {
+                if (this.#disposed || revision !== this.#revision) {
+                    return;
+                }
+                console.warn("PrefViewer: failed to prepare AR Quick Look", error);
+                this.#anchor.dataset.state = "error";
+                this.#anchor.setAttribute("aria-disabled", "false");
+            } finally {
+                if (!this.#disposed && revision === this.#revision) {
+                    this.#anchor.setAttribute("aria-busy", "false");
+                    this.#label();
+                }
+            }
+        });
+        return this.#work;
+    }
+
+    /**
+     * Idempotently removes owned UI/locale handlers and invalidates queued preparation.
+     * Native return listeners remain only while handed-off URLs await return or document unload.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        this.invalidate();
+        this.#unsubscribe();
+        this.#anchor.removeEventListener("click", this.#onClick);
+        this.#anchor.removeEventListener("keydown", this.#onKeyDown);
+        this.#anchor.remove();
+        this.#style.remove();
+        // Used native URLs survive detach until an observed return, or document unload if Safari
+        // emits no return signal. Unused URLs and late preparations are released immediately.
+        if (this.#retired.size === 0) {
+            this.#removeReturnListeners();
+        }
+    }
+}