twd-js 1.3.2 → 1.3.4

package/dist/index.d.ts

@@ -106,8 +106,39 @@ declare type Rule = {
 
 declare type ScreenDom = typeof screen_2;
 
+/**
+ * screenDom - Scoped queries that exclude the TWD sidebar
+ *
+ * Searches only within the main app container (typically #root).
+ * Use this for most queries to avoid matching elements in the sidebar.
+ *
+ * Note: This will NOT find portal-rendered elements (modals, dialogs) that are
+ * rendered outside the root container. For portals, use `screenDomGlobal` instead.
+ */
 export declare const screenDom: ScreenDom;
 
+/**
+ * screenDomGlobal - Global queries that search the entire document.body
+ *
+ * Searches all elements in document.body, including portal-rendered elements
+ * (modals, dialogs, tooltips, etc.).
+ *
+ * ⚠️ WARNING: This may also match elements inside the TWD sidebar if your selectors
+ * are not specific enough. Use more specific queries (e.g., getByRole with name)
+ * to avoid matching sidebar elements.
+ *
+ * Use this when:
+ * - Querying portal-rendered elements (modals, dialogs)
+ * - You need to search outside the root container
+ *
+ * Example:
+ * ```ts
+ * // For a modal rendered via portal
+ * const modal = screenDomGlobal.getByRole('dialog', { name: 'Confirm' });
+ * ```
+ */
+export declare const screenDomGlobal: ScreenDom;
+
 /**
  * Overloads for the `should` function, for best IntelliSense.
  *