Introducing dangerouslyEnterRealms global method.

.changeset/real-jars-repeat.md

@@ -0,0 +1,5 @@
+---
+"@chialab/quantum": minor
+---
+
+Introducing `dangerouslyEnterRealms` global method.

docs/.vitepress/theme/theme.css

@@ -1,7 +1,10 @@
 :root {
-    --vp-c-brand: #ef7d00;
-    --vp-c-brand-light: #ffad42;
-    --vp-c-brand-lighter: #ffad42;
-    --vp-c-brand-dark: #b64f00;
-    --vp-c-brand-darker: #b64f00;
+    --vp-c-brand-1: #f07c00;
+    --vp-c-brand-2: #d56e00;
+    --vp-button-brand-bg: var(--vp-c-brand-1);
+    --vp-button-brand-hover-bg: #d56e00;
+    --vp-button-brand-active-bg: #ce5900;
+
+    --vp-home-hero-name-color: transparent;
+    --vp-home-hero-name-background: linear-gradient(to bottom right, #ffac52 0%, #f07c00 100%);
 }

docs/guide/usage.md

@@ -183,3 +183,26 @@ Insert node at given position in the realm.
 #### `realm.childNodesBySlot(name?: string)`
 
 Get the child nodes of the realm filtered by slot name. If no name is provided, it will provide children with undeclared slot.
+
+## Global methods
+
+The library provide some global methods to manage all realms at once. They are useful to perform global operations like accessibility checks or other tasks that need to access the full DOM tree.
+
+#### `dangerouslyEnterRealms(callback)`
+
+Open all realms and invoke the callback. Once the callback is completed, all realms get closed again.
+
+```ts
+import { dangerouslyEnterRealms } from '@chialab/quantum';
+import { run } from 'axe-core';
+
+const results = await dangerouslyEnterRealms(() => run(document));
+```
+
+#### `dangerouslyOpenRealms`
+
+Open all realms.
+
+#### `dangerouslyCloseRealms`
+
+Close all realms.

src/Realm.js

@@ -28,6 +28,35 @@ export function dangerouslyCloseRealms() {
     opened = false;
 }
 
+/**
+ * Open all realms and call a callback.
+ * @template {(...args: any) => any} T The type of the callback.
+ * @param {T} callback The callback to invoke.
+ * @returns {ReturnType<T>} The result of the callback.
+ */
+export function dangerouslyEnterRealms(callback) {
+    opened = true;
+
+    try {
+        const result = callback();
+        if (result instanceof Promise) {
+            return /** @type {ReturnType<T>} */ (
+                result.finally(() => {
+                    opened = false;
+                    return result;
+                })
+            );
+        }
+        opened = false;
+
+        return result;
+    } catch (err) {
+        opened = false;
+
+        throw err;
+    }
+}
+
 /**
  * Create and attach a realm for a node.
  * @param {HTMLElement & { [REALM_SYMBOL]?: Realm }} node The root node.
@@ -285,14 +314,30 @@ export class Realm {
 
     /**
      * Request an update of the realm.
-     * @param {Function} callback The callback to invoke.
+     * @template {(...args: any) => any} T The type of the callback.
+     * @param {T} callback The callback to invoke.
+     * @returns {ReturnType<T>} The result of the callback.
      */
     requestUpdate(callback) {
         this.dangerouslyOpen();
+
         try {
-            callback();
-        } finally {
+            const result = callback();
+            if (result instanceof Promise) {
+                return /** @type {ReturnType<T>} */ (
+                    result.finally(() => {
+                        this.dangerouslyClose();
+                        return result;
+                    })
+                );
+            }
+            this.dangerouslyClose();
+
+            return result;
+        } catch (err) {
             this.dangerouslyClose();
+
+            throw err;
         }
     }
 

src/index.js

@@ -4,7 +4,14 @@ export { extend };
 export { extendNode } from './Node.js';
 export { extendElement } from './Element.js';
 export { extendTreeWalker } from './TreeWalker.js';
-export { Realm, attachRealm, getRealm, dangerouslyOpenRealms, dangerouslyCloseRealms } from './Realm.js';
+export {
+    Realm,
+    attachRealm,
+    getRealm,
+    dangerouslyOpenRealms,
+    dangerouslyCloseRealms,
+    dangerouslyEnterRealms,
+} from './Realm.js';
 
 if (typeof window !== 'undefined') {
     extend(window);