electron-findbar 0.1.0

package/.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "name": "Debug Main Process",
+        "type": "node",
+        "request": "launch",
+        "cwd": "${workspaceFolder}",
+        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
+        "windows": {
+          "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
+        },
+        "args" : ["sample.js"],
+        "outputCapture": "std"
+      }
+    ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Emerson Capuchi Romaneli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+### Documentation Improvements and Report
+
+---
+
+<p align='center'>
+    <a href="https://github.com/ECRomaneli/handbook" style='text-decoration:none'>
+        <img src="https://i.postimg.cc/0QR0s0Z1/findbar-light.png" alt='Findbar Light Theme'>
+        <img src="https://i.postimg.cc/LXtB6g0Y/findbar-dark.png" alt='Findbar Dark Theme'>
+    </a>
+</p>
+<p align='center'>
+    Chrome-like findbar for your Electron application
+</p>
+<p align='center'>
+    <a href="https://github.com/ECRomaneli/electron-findbar/tags" style='text-decoration:none'>
+        <img src="https://img.shields.io/github/v/tag/ecromaneli/electron-findbar?label=version&sort=semver&style=for-the-badge" alt="Version">
+    </a>
+    <a href="https://github.com/ECRomaneli/electron-findbar/commits/master" style='text-decoration:none'>
+        <img src="https://img.shields.io/github/last-commit/ecromaneli/electron-findbar?style=for-the-badge" alt="Last Commit">
+    </a>
+    <a href="https://github.com/ECRomaneli/electron-findbar/blob/master/LICENSE" style='text-decoration:none'>
+        <img src="https://img.shields.io/github/license/ecromaneli/electron-findbar?style=for-the-badge" alt="License">
+    </a>
+    <a href="https://github.com/ECRomaneli/electron-findbar/issues" style='text-decoration:none'>
+        <img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=for-the-badge" alt="Contributions Welcome">
+    </a>
+</p>
+
+## Installation
+
+Install the `electron-findbar` package via npm:
+
+```sh
+npm install electron-findbar
+```
+
+## Overview
+
+The `electron-findbar` is a `BrowserWindow` component designed to emulate the Chrome findbar layout, leveraging the `webContents.findInPage` method to navigate through matches. Inter-process communication (IPC) is used for interaction between the `main` and `renderer` processes.
+
+### Memory Usage
+
+To optimize memory usage, the Findbar window is created only when the findbar is open. The implementation is lightweight, including only essential code.
+
+## Usage
+
+All public methods are documented with JSDoc and can be referenced during import.
+
+### Importing the Findbar
+
+To import the Findbar class:
+
+```js
+const { Findbar } = require('electron-findbar');
+```
+
+### Creating the Findbar Instance
+
+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 searchable content:
+
+```js
+const findbar = new Findbar(browserWindow);
+```
+
+Alternatively, you can provide a custom `WebContents` as the second parameter. In this case, the first parameter can be any `BaseWindow`, and the second parameter will be the searchable content:
+
+```js
+const findbar = new Findbar(baseWindow, customWebContents);
+```
+
+### Configuring the Findbar
+
+You can customize the Findbar window options using the `setWindowOptions` method:
+
+```js
+findbar.setWindowOptions({ movable: true, resizable: true, alwaysOnTop: true });
+```
+
+To handle the Findbar window directly after it is opened, use the `setWindowHandler` method:
+
+```js
+findbar.setWindowHandler(win => {
+    win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+});
+```
+
+### Opening the Findbar
+
+The Findbar is a child window of the `BaseWindow` passed during construction. It will follow the relative movement of the parent window and must be visible for the Findbar to display:
+
+```js
+findbar.open();
+```
+
+### Finding Text in the Page
+
+Once open, the Findbar appears by default in the top-right corner of the parent window and can be used without additional coding. Alternatively, you can use the following methods to trigger `findInPage` and navigate through matches in the main process:
+
+```js
+/**
+ * Retrieve the last queried value.
+ */
+getLastValue();
+
+/**
+ * Initiate a request to find all matches for the specified text on the page.
+ * @param {string} text - The text to search for.
+ */
+startFind(text);
+
+/**
+ * Select the previous match, if available.
+ */
+findPrevious();
+
+/**
+ * Select the next match, if available.
+ */
+findNext();
+
+/**
+ * Stop the find request.
+ */
+stopFind();
+```
+
+### Closing the Findbar
+
+When the Findbar is closed, its window is destroyed to free memory resources. Use the following method to close the Findbar:
+
+```js
+findbar.close();
+```
+
+A new internal window will be created the next time the `open` method is called. There is no need to instantiate another Findbar for the same parent window.
+
+### Quick Example
+
+Here is a quick example demonstrating how to use the `electron-findbar`:
+
+```js
+const { app, BrowserWindow } = require('electron');
+const { Findbar } = require('electron-findbar');
+
+app.whenReady().then(() => {  
+  const window = new BrowserWindow();
+  window.loadURL('https://github.com/ECRomaneli/electron-findbar');
+
+  // Create and configure the Findbar object
+  const findbar = new Findbar(window);
+
+  // [OPTIONAL] Customize window options
+  findbar.setWindowOptions({ movable: true, resizable: true });
+
+  // [OPTIONAL] Handle the window object when the Findbar is opened
+  findbar.setWindowHandler(win => {
+    win.webContents.openDevTools();
+  });
+
+  // Open the Findbar
+  findbar.open();
+});
+```
+
+## Notes
+
+There are some intentional differences from the Chrome findbar, such as the horizontal margins of the divider and the input text, which has been replaced by a search input to include a clear button (the "x" on the right side).
+
+## Author
+
+Created by [Emerson Capuchi Romaneli](https://github.com/ECRomaneli) (@ECRomaneli).
+
+## License
+
+This project is licensed under the [MIT License](https://github.com/ECRomaneli/handbook/blob/master/LICENSE).
+

package/index.js

@@ -0,0 +1,241 @@
+const { BaseWindow, BrowserWindow, WebContents, BrowserWindowConstructorOptions, Rectangle } = require('electron')
+const path = require('node:path')
+
+class Findbar {
+    /** @type {BaseWindow} */
+    #parent
+
+    /** @type {BrowserWindow} */
+    #window
+
+    /** @type {WebContents} */
+    #searchableContents
+
+    /** */
+    #matches
+
+    /** @type {(findbarWindow: BrowserWindow) => void} */
+    #windowHandler
+
+    /** @type {BrowserWindowConstructorOptions} */
+    #customOptions
+
+    /** @type {string} */
+    #lastValue = ''
+
+    /**
+     * Prepare the findbar.
+     * @param {BaseWindow} parent Parent window.
+     * @param {WebContents | void} webContents Searchable web contents. If not set and the parent is a BrowserWindow, 
+     * the web contents of the parent will be used. Otherwise, an error will be triggered.
+     */
+    constructor (parent, webContents) {
+        this.#parent = parent
+        this.#searchableContents = webContents ?? parent.webContents
+        
+        if (!this.#searchableContents) {
+            throw new Error('There are no searchable web contents.')
+        }
+    }
+    
+    /**
+     * Open the findbar.
+     */
+    open() {
+        if (this.#window) {
+            this.#focusInput()
+            return
+        }
+        this.#window = new BrowserWindow(Findbar.#mergeStandardOptions(this.#customOptions, this.#parent))
+        this.#window.webContents.findbar = this
+
+        this.#registerListeners()
+        this.#setDefaultPosition(this.#parent.getBounds())
+
+        this.#windowHandler && this.#windowHandler(this.#window)
+        
+        this.#window.loadFile(path.join('web', 'findbar.html'))
+    }
+
+    /**
+     * Close the findbar.
+     */
+    close() {
+        this.#window?.close()
+    }
+
+    /**
+     * Get last queried value.
+     */
+    getLastValue() {
+        return this.#lastValue
+    }
+
+    /**
+     * Starts a request to find all matches for the text in the page.
+     * @param {string} text Value to find in page.
+     */
+    startFind(text) {
+        if (this.#lastValue = text) {
+            this.#searchableContents.findInPage(this.#lastValue, { findNext: true })
+        } else {
+            this.stopFind()
+        }
+    }
+
+    /**
+     * Select previous match if any.
+     */
+    findPrevious() {
+        this.#searchableContents.findInPage(this.#lastValue, { forward: false })
+    }
+
+    /**
+     * Select next match if any.
+     */
+    findNext() {
+        this.#searchableContents.findInPage(this.#lastValue, { forward: true })
+    }
+
+    /**
+     * Stops the find request.
+     */
+    stopFind() {
+        this.isOpen() && this.#sendMatchesCount(0, 0)
+        this.#searchableContents.isDestroyed() || this.#searchableContents.stopFindInPage("clearSelection")
+    }
+
+    /**
+     * Return if the findbar is open or not.
+     * @returns {boolean} True, if the findbar is open. Otherwise, false.
+     */
+    isOpen() {
+        return !!this.#window
+    }
+
+    /**
+     * Provides a customized set of options to findbar window before open. Note
+     * that the options below are necessary for the correct functioning and cannot
+     * be overridden:
+     * - options.parent (value: parentWindow)
+     * - options.frame (value: false)
+     * - options.transparent (value: true)
+     * - options.maximizable (value: false)
+     * - options.minimizable (value: false)
+     * - options.skipTaskbar (value: true)
+     * - options.fullscreenable (value: false)
+     * - options.webPreferences.nodeIntegration (value: true)
+     * - options.webPreferences.contextIsolation (value: false)
+     * @param {BrowserWindowConstructorOptions} customOptions Custom window options.
+     */
+    setWindowOptions(customOptions) {
+        this.#customOptions = customOptions
+    }
+
+    /**
+     * Set a window handler capable of changing the findbar window settings after opening.
+     * @param {(findbarWindow: BrowserWindow) => void} windowHandler Window handler.
+     */
+    setWindowHandler(windowHandler) {
+        this.#windowHandler = windowHandler
+    }
+
+    /**
+     * Merge custom, defaults, and fixed options.
+     * @param {Electron.BrowserWindowConstructorOptions} options Custom options.
+     * @param {BaseWindow | void} parent Parent window, if any.
+     * @returns {Electron.BrowserWindowConstructorOptions} Merged options.
+     */
+    static #mergeStandardOptions(options, parent) {
+        if (!options) { options = {} }
+        options.width = options.width ?? 372
+        options.height = options.height ?? 52
+        options.resizable = options.resizable ?? false
+        options.movable = options.movable ?? false
+        options.parent = parent
+        options.frame = false
+        options.transparent = true
+        options.maximizable = false
+        options.minimizable = false
+        options.skipTaskbar = true
+        options.fullscreenable = false
+        if (!options.webPreferences) { options.webPreferences = {} }
+        options.webPreferences.nodeIntegration = true
+        options.webPreferences.contextIsolation = false
+        return options
+    }
+
+    /**
+     * Register all event listeners.
+     */
+    #registerListeners() {
+        const showCascade = () => this.#window.isVisible() || this.#window.show()
+        const hideCascade = () => this.#window.isVisible() && this.#window.hide()
+
+        this.#parent.prependListener('show', showCascade)
+        this.#parent.prependListener('hide', hideCascade)
+
+        this.#window.once('closed', () => {
+            this.#parent.off('show', showCascade)
+            this.#parent.off('hide', hideCascade)
+            this.#window = null
+            this.stopFind()
+        })
+
+        this.#searchableContents.prependOnceListener('destroyed', () => { this.close() })
+        this.#searchableContents.prependListener('found-in-page', (_e, result) => {
+            this.#matches = result
+            this.#sendMatchesCount(result.activeMatchOrdinal, result.matches)
+        })
+    }
+
+    /**
+     * Set default findbar position.
+     * @param {Rectangle} parentBounds 
+     */
+    #setDefaultPosition(parentBounds) {
+        const s = this.#window.getSize()
+        this.#window.setBounds({
+            x: parentBounds.x + parentBounds.width - s[0] - 20,
+            y: parentBounds.y - ((s[1] / 4) | 0)
+        })
+    }
+
+    /**
+     * Send to renderer the active match and the total.
+     * @param {number} active Active match.
+     * @param {number} total Total matches.
+     */
+    #sendMatchesCount(active, total) {
+        this.#window.webContents.send('electron-findbar/matches', { active, total })
+    }
+
+    /**
+     * Select input text.
+     */
+    #focusInput() {
+        this.#window.webContents.send('electron-findbar/input-focus')
+    }
+}
+
+/**
+ * Define IPC events.
+ */
+(({ ipcMain }) => {
+    ipcMain.handle('electron-findbar/initial-input', e => {
+        const findbar = e.sender.findbar
+        findbar.startFind(findbar.getLastValue())
+        return findbar.getLastValue()
+    })
+    
+    ipcMain.on('electron-findbar/input-change', (e, value) => e.sender.findbar.startFind(value))
+    ipcMain.on('electron-findbar/previous', e => e.sender.findbar.findPrevious())
+    ipcMain.on('electron-findbar/next', e => e.sender.findbar.findNext())
+    ipcMain.on('electron-findbar/close', e => {
+        const findbar = e.sender.findbar
+        findbar.stopFind()
+        findbar.close()
+    })
+}) (require('electron'))
+
+module.exports = { Findbar }

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "electron-findbar",
+  "version": "0.1.0",
+  "description": "Chrome-like findbar for your Electron app.",
+  "main": "index.js",
+  "scripts": {
+    "sample": "electron sample.js",
+    "test": "node test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ECRomaneli/electron-findbar.git"
+  },
+  "keywords": [
+    "findbar",
+    "electron-findbar",
+    "electron",
+    "chrome-findbar",
+    "search"
+  ],
+  "author": "ECRomaneli",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ECRomaneli/electron-findbar/issues"
+  },
+  "homepage": "https://github.com/ECRomaneli/electron-findbar#readme",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "devDependencies": {
+    "electron": ">=12.0.0"
+  }
+}

package/sample.js

@@ -0,0 +1,23 @@
+const { BrowserWindow, app, Menu } = require('electron')
+const { Findbar } = require('./index')
+
+app.whenReady().then(() => {  
+  const window = new BrowserWindow()
+  window.loadURL('https://github.com/ECRomaneli/electron-findbar#readme')
+
+  const findbar = new Findbar(window)
+  findbar.setWindowOptions({ movable: !true, resizable: true })
+  findbar.setWindowHandler(win => {
+    win.webContents.openDevTools()
+  })
+  findbar.open()
+
+  const contextMenu = Menu.buildFromTemplate([
+    { role: 'separator' },
+    { label: 'Open findbar', click: () => findbar.open(), accelerator: 'CommandOrControl+F' },
+    { label: 'Close findbar', click: () => findbar.isOpen() && findbar.close(), accelerator: 'Esc', registerAccelerator: true, acceleratorWorksWhenHidden: true }
+  ])
+
+  Menu.setApplicationMenu(contextMenu)
+  
+})

package/web/app.css

@@ -0,0 +1,106 @@
+*, *:before, *:after {
+    box-sizing: border-box;
+}
+
+body {
+    margin: 0;
+    padding: 0;
+    font-weight: normal;
+    height: 100vh;
+}
+
+nav {
+    --bg-color: #fff;
+    --border: #eee;
+    --color: #626262;
+    --input-color: #1f1f1f;
+    --btn-hover-color: #ccc;
+    --btn-active-color: #bbb;
+}
+
+@media (prefers-color-scheme: dark) {
+    nav {
+        --bg-color: #1f1f1f;
+        --border: #2f2f2f;
+        --color: #a9a9aa;
+        --input-color: #e3e3e3;
+        --btn-hover-color: #333;
+        --btn-active-color: #444;
+    }
+}
+
+svg {
+    fill: none;
+    stroke: var(--color);
+    stroke-width: 2;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+}
+
+nav {
+    display: flex;
+    align-items: center;
+    width: 100%;
+    height: 100%;
+    padding: .75rem;
+    font-family: system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue","Noto Sans","Liberation Sans",Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";
+    background-color: var(--bg-color);
+    color: var(--color);
+    font-size: .75rem;
+    border-radius: 10px;
+    border: 1px solid var(--border);
+    -webkit-app-region: drag;
+}
+
+nav > span,
+nav > .divider {
+    margin-right: .75rem;
+    user-select: none;
+}
+
+input {
+    width: 100%;
+    background-color: transparent;
+    color: var(--input-color);
+    border: none;
+    outline: none;
+    -webkit-app-region: no-drag;
+}
+
+.divider {
+    width: 2px;
+    height: 100%;
+    background-color: var(--btn-hover-color);
+}
+
+.btn-group {
+    display: flex;
+}
+
+.btn-group > :not(:last-child) {
+    margin-right: .5rem;
+}
+
+.btn-group > div {
+    border-radius: 50%;
+    cursor: default;
+    width: 26px;
+    height: 26px;
+    padding: 3px;
+    text-align: center;
+    transition: .1s linear all;
+    -webkit-app-region: no-drag;
+}
+
+.btn-group > div:hover {
+    background-color: var(--btn-hover-color);
+}
+
+.btn-group > div:active {
+    background-color: var(--btn-active-color);
+}
+
+.btn-group > .disabled {
+    opacity: .4;
+    background-color: transparent !important;
+}

package/web/app.js

@@ -0,0 +1,51 @@
+const { ipcRenderer } = require('electron')
+
+const $remote = {
+    getInitialInput: async () => ipcRenderer.invoke('electron-findbar/initial-input'),
+    inputChange: (value) => { ipcRenderer.send('electron-findbar/input-change', value) },
+    previous: () => { ipcRenderer.send('electron-findbar/previous') },
+    next: () => { ipcRenderer.send('electron-findbar/next') },
+    close: () => { ipcRenderer.send('electron-findbar/close') },
+    onMatchesChange: (listener) => { ipcRenderer.on('electron-findbar/matches', listener) },
+    onInputFocus: (listener) => { ipcRenderer.on('electron-findbar/input-focus', listener) }
+}
+
+let canRequest = true, canMove = false
+
+function inputChange(e) {
+    canRequest = false
+    $remote.inputChange(e.target.value)
+}
+
+function move(next) {
+    if (canRequest && canMove) {
+        canRequest = false
+        next ? $remote.next() : $remote.previous()
+    }
+}
+
+document.addEventListener('DOMContentLoaded', async () => {
+    const inputEl = document.getElementById('input')
+    const matchesEl = document.getElementById('matches')
+    const moveBtns = [...document.getElementsByClassName('disabled')]
+
+    $remote.onMatchesChange((_, m) => {
+        canRequest = true
+        matchesEl.innerText = inputEl.value ? m.active + '/' + m.total : ''
+
+        for (var moveBtn of moveBtns) {
+            (canMove = m.total > 1) ? 
+                moveBtn.classList.remove('disabled') :
+                moveBtn.classList.add('disabled')
+        }
+    })
+
+    $remote.onInputFocus(async () => {
+        inputEl.setSelectionRange(0, inputEl.value.length)
+        inputEl.focus()
+    })
+
+    inputEl.value = await $remote.getInitialInput()
+    inputEl.setSelectionRange(0, inputEl.value.length)
+    inputEl.focus()
+})

package/web/findbar.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html>
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Findbar</title>
+    <link rel="stylesheet" href="app.css">
+<body>
+    <nav>
+        <input id='input' oninput="inputChange(event)" type="search" spellcheck="false">
+        <span id="matches"></span>
+        <div class="divider"></div>
+        <div class="btn-group">
+            <div onclick="move(false)" class="disabled">
+                <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+                    <path d="M7 15L12 10L17 15"/>
+                </svg>
+            </div>
+            <div onclick="move(true)" class="disabled">
+                <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+                    <path d="M7 10L12 15L17 10"/>
+                </svg>
+            </div>
+            <div onclick="$remote.close()">
+                <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+                    <path d="M7 17.5L12 12.5L17 17.5"/>
+                    <path d="M7 7.5L12 12.5L17 7.5"/>
+                </svg>
+            </div>
+        </div>
+    </nav>
+    
+    <script src="app.js"></script>
+</body>
+
+</html>