electron-findbar 2.0.1 → 3.1.0

package/README.md

@@ -44,7 +44,7 @@ const Findbar = require('electron-findbar')
 You can pass a `BrowserWindow` instance as a single parameter to use it as the parent window. The `BrowserWindow.WebContents` will be used as the findable content:
 
 ```js
-// Create or retrieve the findbar associated to the browserWindow.webContents. If a new findbar is created, the browserWindow is used as parent.
+// Create or retrieve the findbar associated to the browserWindow.webContents or baseWindow.contentView.children[0]. If a new findbar is created, the browserWindow is used as parent.
 const findbar = Findbar.from(browserWindow)
 ```
 
@@ -55,10 +55,10 @@ Alternatively, you can provide a custom `WebContents` as the second parameter. I
 const findbar = Findbar.from(baseWindow, webContents)
 ```
 
-Is also possible to create a findbar without a parent window (even though it is not recommended):
+Is also possible to create a findbar providing only the web contents. The BaseWindow.getAllWindows() will be used to query for the parent window:
 
 ```js
-// Create or retrieve the findbar associated to the webContents. If a new findbar is created, it will be displayed in the middle of the screen without a parent to connect to.
+// Create or retrieve the findbar associated to the webContents.
 const findbar = Findbar.from(webContents)
 ```
 
@@ -146,9 +146,20 @@ app.whenReady().then(() => {
 })
 ```
 
-### Configuring Keyboard Shortcuts
+### Keyboard Shortcuts
 
-The Findbar component can be controlled using keyboard shortcuts. Below are two implementation approaches to help you integrate search functionality seamlessly into your application's user experience.
+The Findbar component can be controlled using keyboard shortcuts. The following shortcuts are available by default:
+
+| Shortcut | Description |
+|----------|-------------|
+| Enter | Move to next match |
+| Shift+Enter | Move to previous match |
+| Esc | Close the findbar |
+
+
+### Configuring Other Shortcuts
+
+Below are two implementation approaches to help you integrate search functionality seamlessly into your application's user experience.
 
 **Note:** The following examples demonstrate only the ideal (happy path) scenarios. For production use, make sure to thoroughly validate all inputs and handle edge cases appropriately.
 
@@ -157,27 +168,35 @@ The Findbar component can be controlled using keyboard shortcuts. Below are two
 The `before-input-event` approach allows you to capture keyboard events directly in the main process before they're processed by the web contents, giving you precise control:
 
 ```js
-window.webContents.on('before-input-event', (event, input) => {
-  // Detect Ctrl+F (Windows/Linux) or Command+F (macOS)
-  if ((input.control || input.meta) && input.key.toLowerCase() === 'f') {
-    // Prevent default browser behavior
-    event.preventDefault()
-    
-    // Access and open the findbar
-    const findbar = Findbar.from(window)
-    if (findbar) {
-      findbar.open()
+webContents.on('before-input-event', (event, input) => {
+    if (input.shift || input.alt) { return }
+
+    const key = input.key.toLowerCase()
+
+    // Detect Ctrl+F (Windows/Linux) or Command+F (macOS)
+    if (input.control || input.meta) {
+        if (key === 'f') {
+            // Prevent default behavior
+            event.preventDefault()
+            
+            // Access and open the findbar
+            Findbar.from(webContents).open()
+        }
+        return
     }
-  }
-  
-  // Handle Escape key to close the findbar
-  if (input.key === 'Escape') {
-    const findbar = Findbar.from(window)
-    if (findbar && findbar.isOpen()) {
-      event.preventDefault()
-      findbar.close()
+
+    // Handle Escape key to close the findbar
+    if (key === 'escape') {
+      const findbar = Findbar.fromIfExists(webContents)
+
+      if (findbar?.isOpen()) {
+        // Prevent default behavior
+        event.preventDefault()
+
+        // Close the findbar
+        findbar.close()
+      }
     }
-  }
 })
 ```
 
@@ -198,12 +217,12 @@ appMenu.append(new MenuItem({
   submenu: [
     { 
       label: 'Find in Page', 
-      click: () => Findbar.from(parent)?.open(), 
+      click: () => Findbar.from(parent).open(), 
       accelerator: 'CommandOrControl+F' 
     },
     { 
       label: 'Close Find', 
-      click: () => Findbar.from(parent)?.close(), 
+      click: () => Findbar.from(parent).close(), 
       accelerator: 'Esc' 
     }
   ]
@@ -308,6 +327,49 @@ FindbarRemote.open()
 FindbarRemote.inputChange('findIt')
 ```
 
+## Changing the Parent Window
+
+There are scenarios where you might need to change the parent window.
+
+### Using updateParentWindow
+
+The `updateParentWindow` method allows you to change the parent window while preserving the findbar instance and its state:
+
+```javascript
+// Create a findbar for the initial window
+const findbar = Findbar.from(oldWindow, webContents)
+
+// Later, when you need to change the parent:
+findbar.updateParentWindow(newWindow)
+```
+
+This approach keeps the same findbar instance connected to the same webContents, but changes which window it's attached to. The findbar will close immediately.
+
+### Using detach
+
+Alternatively, the `detach` method disconnects a findbar instance from its webContents, allowing you to create a new instance in the next `Findbar.from` call:
+
+```javascript
+// Get the existing findbar
+const oldFindbar = Findbar.fromIfExists(webContents)
+
+// Detach it to free the association
+if (oldFindbar) {
+  oldFindbar.detach()
+}
+
+// Now create a new findbar with a different parent
+const newFindbar = Findbar.from([newWindow, ]webContents)
+```
+
+This approach is useful when you want to completely reset the findbar's configuration or when moving between very different window configurations.
+
+### Important Considerations
+
+- If the findbar is currently open when you change the parent window, it will automatically close.
+- Window options and handlers will be preserved when using `updateParentWindow`.
+- After calling `detach`, the old findbar instance can no longer be used.
+
 ## Author
 
 Created by [Emerson Capuchi Romaneli](https://github.com/ECRomaneli) (@ECRomaneli).

package/index.js

@@ -44,28 +44,29 @@ class Findbar {
      * Configure the findbar and link to the web contents.
      * 
      * @overload
+     * @param {WebContents} webContents Findable web contents. The parent window will be defined by using BaseWindow.getAllWindows() and
+     * matching the webContents with the webContents of the window or its contentView children.
+     * @returns {Findbar} The findbar instance if it exists.
+     * @throws {Error} If no webContents is provided.
+     * 
+     * @overload
      * @param {BrowserWindow} browserWindow Parent window.
-     * @param {WebContents} [customWebContents] Custom findable web contents. If not provided, the web contents of the BrowserWindow will be used.
+     * @param {WebContents} [customWebContents] Custom findable web contents. If not provided, the browserWindow.webContents will be used.
      * @returns {Findbar} The findbar instance if it exists.
      *
      * @overload
      * @param {BaseWindow} baseWindow Parent window.
-     * @param {WebContents} webContents Findable web contents.
-     * @returns {Findbar} The findbar instance if it exists.
-     * @throws {Error} If no webContents is provided.
-     *     * 
-     * @overload
-     * @param {WebContents} webContents Findable web contents. The parent window will be undefined.
+     * @param {WebContents} [webContents] Custom findable web contents. If not provided, the win.contentView.children[0] will be used.
      * @returns {Findbar} The findbar instance if it exists.
      * @throws {Error} If no webContents is provided.
      */
     constructor (parent, webContents) {
         if (isFindable(parent)) {
-            this.#parent = void 0
             this.#findableContents = parent
+            this.#parent = Findbar.#getBaseWindowFromWebContents(this.#findableContents)
         } else {
             this.#parent = parent
-            this.#findableContents = webContents ?? parent.webContents
+            this.#findableContents = webContents ?? Findbar.#retrieveWebContents(parent)
         }
 
         if (!this.#findableContents) {
@@ -73,8 +74,10 @@ class Findbar {
         }
 
         this.#findableContents._findbar = this
+
+        this.#findableContents.once('destroyed', () => { this.detach() })
     }
-    
+
     /**
      * Open the findbar. If the findbar is already opened, focus the input text.
      * @returns {void}
@@ -92,7 +95,6 @@ class Findbar {
         this.#registerListeners()
 
         this.#windowHandler && this.#windowHandler(this.#window)
-        
         this.#window.loadFile(`${__dirname}/web/findbar.html`)
     }
 
@@ -101,10 +103,30 @@ class Findbar {
      * @returns {void}
      */
     close() {
-        if (!this.#window || this.#window.isDestroyed()) { return }
-        if (!this.#window.isVisible()) { this.#window.close(); return }
-        this.#window.on('hide', () => { this.#window.close() })
-        this.#window.hide()
+        if (this.#window && !this.#window.isDestroyed()) {
+            this.#window.close()
+        }
+    }
+
+    /**
+     * Detach the findbar from the web contents and close it if opened. After detaching, the findbar instance will be unusable.
+     * @returns {void}
+     */
+    detach() {
+        this.close()
+        this.#findableContents._findbar = void 0
+        if (this.#window) { this.#window.webContents._findbar = void 0 }
+    }
+
+    /**
+     * Update the parent window of the findbar.
+     * @param {BaseWindow} [newParent] - The new parent window. If not provided, the parent will be set to the window containing the web contents.
+     * @returns {void}
+     */
+    updateParentWindow(newParent) {
+        if (this.#parent === newParent) { return }
+        this.close()
+        this.#parent = newParent ?? Findbar.#getBaseWindowFromWebContents(this.#findableContents)
     }
 
     /**
@@ -235,6 +257,32 @@ class Findbar {
         this.#boundsHandler = boundsHandler
     }
 
+    #registerKeyboardShortcuts(event, input) {
+        if (input.meta || input.control || input.alt) { return }
+
+        const key = input.key.toLowerCase()
+
+        if (input.shift) {
+            if (key === 'enter') {
+                this.findPrevious()
+                event.preventDefault()
+            }
+            return;
+        }
+
+        if (key === 'enter') {
+            this.findNext()
+            event.preventDefault()
+            return;
+        }
+
+        if (key === 'escape') {
+            if (this.isOpen()) {
+                this.close()
+                event.preventDefault()
+            }
+        }
+    }
     /**
      * @param {Electron.FindInPageOptions} options 
      */
@@ -269,7 +317,7 @@ class Findbar {
             this.#parent.prependListener('move', boundsHandler)
         }
 
-        this.#window.once('close', () => {
+        this.#window.once('closed', () => {
             if (this.#parent && !this.#parent.isDestroyed()) {
                 this.#parent.off('show', showCascade)
                 this.#parent.off('hide', hideCascade)
@@ -281,6 +329,7 @@ class Findbar {
         })
 
         this.#window.prependOnceListener('ready-to-show', () => { this.#window.show() })
+        this.#window.webContents.prependListener('before-input-event', this.#registerKeyboardShortcuts.bind(this))
 
         this.#findableContents.prependOnceListener('destroyed', () => { this.close() })
         this.#findableContents.prependListener('found-in-page', (_e, result) => { this.#sendMatchesCount(result.activeMatchOrdinal, result.matches) })
@@ -310,6 +359,24 @@ class Findbar {
         this.#window.webContents.send('electron-findbar/input-focus')
     }
 
+    /**
+     * Retrieve web contents from a BrowserWindow or BaseWindow.
+     * @param {BrowserWindow | BaseWindow} window 
+     * @returns {WebContents | undefined} The web contents if any.
+     */
+    static #retrieveWebContents(window) {
+        return window.webContents ?? window.contentView?.children[0]
+    }
+
+    /**
+     * Get the parent window from web contents.
+     * @param {WebContents} cont 
+     * @returns {BaseWindow | undefined} Parent window if any.
+     */
+    static #getBaseWindowFromWebContents(cont) {
+        return BaseWindow.getAllWindows().find(win => win.webContents === cont || win.contentView.children.some(child => child.webContents === cont))
+    }
+
     /**
      * Set default findbar position.
      * @param {Rectangle} parentBounds 
@@ -358,25 +425,25 @@ class Findbar {
      * If no findbar instance exists, it will return a new one linked to the web contents.
      * 
      * @overload
-     * @param {BrowserWindow} browserWindow Parent window.
-     * @param {WebContents} [customWebContents] Custom findable web contents. If not provided, the web contents of the BrowserWindow will be used.
+     * @param {WebContents} webContents Findable web contents. The parent window will be defined by using BaseWindow.getAllWindows() and
+     * matching the webContents with the webContents of the window or its contentView children.
      * @returns {Findbar} The findbar instance if it exists.
+     * @throws {Error} If no webContents is provided.
      * 
      * @overload
-     * @param {WebContents} webContents Findable web contents. The parent window will be undefined.
+     * @param {BrowserWindow} browserWindow Parent window.
+     * @param {WebContents} [customWebContents] Custom findable web contents. If not provided, the browserWindow.webContents will be used.
      * @returns {Findbar} The findbar instance if it exists.
-     * @throws {Error} If no webContents is provided.
-     * 
+     *
      * @overload
      * @param {BaseWindow} baseWindow Parent window.
-     * @param {WebContents} webContents Findable web contents.
+     * @param {WebContents} [webContents] Custom findable web contents. If not provided, the win.contentView.children[0] will be used.
      * @returns {Findbar} The findbar instance if it exists.
      * @throws {Error} If no webContents is provided.
      */
      static from(windowOrWebContents, customWebContents) {
-        let webContents = isFindable(windowOrWebContents) ?
-            windowOrWebContents : customWebContents ?? windowOrWebContents.webContents
-
+        const webContents = isFindable(windowOrWebContents) ? windowOrWebContents : customWebContents ?? Findbar.#retrieveWebContents(windowOrWebContents)
+        if (!webContents) { throw new Error('[Findbar] There are no searchable web contents.') }
         return webContents._findbar || new Findbar(windowOrWebContents, customWebContents)
     }
 
@@ -386,7 +453,9 @@ class Findbar {
      * @returns {Findbar | undefined} The findbar instance if it exists, otherwise undefined.
      */
     static fromIfExists(windowOrWebContents) {
-        return (isFindable(windowOrWebContents) ? windowOrWebContents : windowOrWebContents.webContents)._findbar
+        const webContents = isFindable(windowOrWebContents) ? windowOrWebContents : Findbar.#retrieveWebContents(windowOrWebContents)
+        if (!webContents) { throw new Error('[Findbar] There are no searchable web contents.') }
+        return webContents._findbar
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electron-findbar",
-  "version": "2.0.1",
+  "version": "3.1.0",
   "description": "Chrome-like findbar for your Electron app.",
   "main": "index.js",
   "files": [