@fvastu/bens NPM

About The Project

In Manifest V3, the Chrome extension platform moves from background pages to service workers. When migrating to this new background context, you'll need to keep two main things in mind:

Service workers have a short life and are automatically closed when not in use
Service workers don't have access to DOM.

Without having access (directly) to DOM, any type of operations with the intent of modify it is tedious and not straightforward. That's why Bens comes to your aid. Directly from your service worker, you can:

Display overlay popups
Display notifications with a high degree of flexibility and customization.

Built With

Typescript, rollup on top of Chrome Extension API (Manifest V3).

Getting Started

Prerequisites

You should use this package in the context of Chrome extension.

npm
```
npm install npm@latest -g
```

tabs, scripting permissions inside manifest.json

	  ```bash
	 "permissions": [
	    ...
 "tabs",
 "scripting",
 ...
	  ],
	  ```

Installation

Install NPM package

npm install @fvastu/bens

...and you are ready to go!

Preview

This is what you will get by default, using the light theme

Usage

After import bens, you will have to just invoke createModal giving as input a configuration object and an id of the tab where you want to show the overlay. Your code should look like something like this:

import { createModal } from '@fvastu/bens'

// Retrieve all tabs using chrome API, then pick the first one
const tab = await chrome.tabs.query({})[0];

// Show modal in the tab chosen
createModal(
    {
      theme: 'light',
      blurBackground: true,
      useAnimation: true,
      logo: 'https://svgshare.com/i/pKb.svg',
      text: "Please leave a star!",
      subtext: 'Would you mind sparing some feedback?',
      buttonContent: 'Confirm',
      cancelContent: 'Cancel',
      onConfirmClick: () => console.log('buttonConfirm Clicked'),
      onCancelClick: () => console.log('buttonCancel Clicked'),
      onOpen: () => console.log('Popup Open'),
      onClose: () => console.log('Popup Closed'),
    },
    tab.id
)

API

The function createModal accepts an object with the following parameters:

name	type	description	default	must?
`text`	`string`	Primary text shows in bold with the "main" message	""	required
`subtext`	`string`	Secondary text shown under the primary text	""	optional
`logo`	`string`	URL to the logo	""	optional
`theme`	`string`	"dark" \| "light"	"light"	optional
`useAnimation`	`boolean`	Show a fadeIn animation when the overlay is shown	true	optional
`blurBackground`	`boolean`	Blur the background when the overlay is shown	true	optional
`hideAfter`	`number`	Hide the overlay after a the provided amount. N.B. if the delay is too big (e.g. greater than 30 seconds) there could be problems due to SW change to idle states.	don't hide	optional
`buttonContent`	`string`	Label shown inside the confirm button	""	optional
`cancelContent`	`string`	Label shown inside the cancel button	""	optional
`onConfirm`	`fn: void`	function that get's executed when the user clicks on confirm button (left button).	do Nothing	optional
`onCancel`	`fn: void`	function that get's executed when the user clicks on cancel button (right button)	do Nothing	optional
`onOpen`	`fn: void`	function that get's executed when the modal is opened, this can be useful for things like adding body-padding, sending stats to a server etc.	do Nothing	optional
`onClose`	`fn: void`	function that get's executed when the modal is closed, this can be useful for things like removing body-padding, etc.	do Nothing	optional

Roadmap

Add overlay popup
Dark and light theme for overlay popup
Add notifications popup
Dark and light theme for notifications popup
Add additional Templates and animation
Improve styles injection to easily personalize the UI

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!