peterhil/spellbook

Spellbook is a WebExtension to easily add new bookmarks to correct categories

Spellbook

Spellbook is a browser extension for easily managing thousands of bookmarks with novel UI innovations.

Installation

Get it now for Google Chrome or Mozilla Firefox.

Unpacked installation

pnpm install
pnpm run build

Then add the dist directory as unpacked extension to Chrome or compatible browser.

Development

pnpm install
pnpm run dev

Then add the dev directory as unpacked extension to Chrome or compatible browser.

Testing

pnpm run test
pnpm run test:puppeteer

Technology stack

I strive to use libraries that are well written and most importantly extremely small in size.

For now the stack is:

• Svelte
• Spectre.css – lightweight, responsive and modern CSS Framework
• Rambda (differences) to Ramda
• Kefir – fast and light Reactive Programming library inspired by Bacon.js and RxJS
• ESLint – Pluggable JavaScript linter
• Rollup

Licensing

Copyright © 2018–2023 Peter Hillerström and contributors

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

Other licenses

• The lib/rxjs.js file implements fromEventPattern function from RxJS in Kefir and is licensed under Apache Software License.

spellbook's Issues

Use derived store for all directories

Use derived store to get category search results quickly

Reorganize the content of the popup for more flexible UI

This allows flexible UI for:

• showing search results on popup (for existing bookmarks and categories – needs more thought for UI)
• editing capabilities in the future

Tasks:

• Move category selector on top, and show existing bookmarks below
• Move URL to be above the title

Lint code on pre commit hook

Fix dropdown logic to use a store

Dropdown visibility logic is currently very cumbersome. It would greatly benefit from using Svelte store for state management.

Navigate existing bookmarks on popup

• Navigate the category tree with mouse or keyboard
• Allow navigating to parent categories
• Use arrows and other keyboard shortcuts for navigating the category tree

Update all dependencies and audit npm packages

Wrong page information shown on popup

When inactive page changes title or url, the popup information is wrong

Websites that change the window title on notifications cause the popup to show information for the page that was last changed – even if it is not the active one.

Technical analysis

The bug is caused by currentTab stream not properly filtering these changes out. Or in other words, it should only emit events on user generated changes.

Suggested solution

The solution is to make sure that only user generated changes to title or url pass the filtering on currentTab stream.

Edit existing bookmarks

Enable editing existing bookmarks instead of saving new ones.

Tasks:

• Use saved bookmark information on popup
• Make sure no duplicates are saved (unless user intended to do so: provide UI)
• Show status on popup buttons (Firefox has Cancel / Remove bookmark as secondary button)
• If user is editing existing bookmark, submit the form on enter (currently it is prevented)
• Allow URLs to be editable from the popup & update the existing bookmarks accordingly

Show saved bookmark information on popup

• Get information of saved bookmarks into popup
• Polish the UI

Later:

• #78
• #85

Directory view: Bookmark listing

Show all categories and bookmarks alphabetically on left and right pane initially.

Left side:

• Show categories on the left side
• Show main categories first

Right side:

• Show selected category contents on the right side
• Scroll to (first) selected category on the left side when selecting bookmarks on the right side

Select and unselect categories

• Implement caching service for all bookmarks
  • Initialize service with all bookmarks
  • Update cache on bookmark modifying events
• Select and unselect categories by single click and update the right side content accordingly
  • Split left pane and right pane into separate tags and communicate with events
  • Observe events from these tags with Kefir and update views accordingly

Optimise asynchronous requests

Optimise asynchronous requests to browser APIs to improve responsiveness

• Throttle, delay and/or debounce the bookmarks.search requests to prevent searching while the user is still typing
• Work around Chrome bug #1213925: Cannot retrieve tab on browser.tabs.onActivated in an extension

Sort results also by the parent category name

You might have many categories which have the same name, for eaxmple "Tutorials" for different programming languages.
To make things easier to find, sort the results first by the category name and then by the parent category name.

Edit:

Now the sorting actually works in tree order (the order the bookmarks are in) – and this could be made alphabetic.
The above sorting could be an option in the UI or preferences.

Firefox WebExtension support

Firefox (WebExtension) support

I want to add support for Firefox using test driven development.

That will also help me writing good quality browser (integration/functional) and unit tests for Chrome, which do not still exist.

Implementation plan

– Sinon-chrome could be used for mocking and spying the browser APIs
– Puppeteer is a good candidate for implementing live browser testing.

The Browser APIs should be abstracted by functional strategy pattern and code from other parts of the extension than platform/ should not call different browser APIs directly.

Improve usability of the popup

Ideas

• Make first menu item focused on tab instead of the menu element
• Close the dropdown when an item is selected
• Restrict the maximum width of the popup
• Open the dropdown again when clicking the search field or search icon

Replace Fkit with Ramda

Fkit does not seems to be updated or at least the documentation page does not respond. Replace it with Ramda.

• Replace Fkit usage with Ramda everywhere
• Update documentation
• Update changelog

Add bookmarks from context menu

Thanks for your work on this so far.

It'd be really useful for me to be able to trigger your extension to add a bookmark using a right-click on a given link without having to visit the page, as is possible with the regular bookmark function in Firefox. This seems like a scenario not unique to me and I hope it's ok that I suggest this as a feature to add.

Try out Vite and Snowpack

Try out Vite and/or Snowpack (unmaintained)

Tried out:

• Vite
• ESbuild

Ended up coming back to Rollup, because it allows precise control on how the packaging and code splitting works.

Vite seemed promising, but it is too much intended for web sites. On the plus side it handles Typescript out of the box.

I gave up on ESbuild, because the plugin scene seemed unmaintained.

Use Svelte stores for state management

Notes:

• Make components represent the state in a simple view and not have much logic or state on their own.
• Remember that Svelte store contract is implemented by reactive streams (RXJS/Kefir observervables), but do not overuse Kefir when simpler solutions would work.

Tasks:

• Use store for dropdown state #47
• Use store for search #63
• Use Svelte store for all bookmarks #48
• Use derived store for directories #49

Firefox: Fix popup height after selection

Popup sizing does not seem to work correctly in Firefox

There are a lot of bugs on Firefox related to this:

• 1222454 - Not possible to set the width and height of the popup
• 1190665 - Automatically determine size for browser action popup based on HTML content
• 1215025 - Popup size does not respond to content change.

Steps to reproduce

1. Open popup
2. Search for some existing category
3. Select one category
4. Move mouse away from dropdown
5. The popup height will stay too large

Notes

After investigating this, I think the problem is that the dropdown should be hidden with JS after a selection is made, and remove the styles that keep the dropdown open on hover.

Observations

• When any of the dropdown toggles receives focus, the dropdown height updates on Firefox to correct height
• It apparently helped on Chrome a long time ago to set both html and body width and height
• On uBlock origin this works with the show more and show less buttons. It uses Flex styling and some CSS utility classes like desktop and inTab.

Possible solutions

• Maybe use blur or focusout event on CategorySelector and CategorySearch in addition to focus event?
• Use flex box styling?

Explore existing bookmarks from the popup

Enable browsing existing bookmarks from the popup without adding a new bookmark

• Add tab bar on top of the popup that switches between popup views
• Add another popup view to browse the category tree
• Add third popup view to search bookmarks and categories
• Enable switching to edit mode?

For updating the child categories, see on:categorySelection={updateChildren} on ChildCategories.

Use webextension-polyfill

Use webextension-polyfill

Try out WebExtensions polyfill by Mozilla or Web-Extension Polyfill for TypeScript
if using Typescript already.

• Basic setup
• Using promise based APIs
• Examples
• Usage with Typescript
• Known limitations

Highlights

Two way messaging

It's also possible to use Promises effectively using two-way messaging. Communication between a background page and a tab content script, for example, looks something like this from the background page side:

browser.tabs.sendMessage(tabId, "get-ids").then(results => {
  processResults(results);
});

Translations wanted

Contributions welcome

Currently there are translations for English and Finnish. High quality and maintained translation contributions are welcome for other languages.

Adding a translation

This commit on v0.3.2 shows what is needed to make a new translation.

Steps to add a translation

– Write a new file _locales/en_GB/messages.jsonunder subdirectory with en_GB replaced by the correct locale code
– Add copying of the new file to rollup.config.js

In the future, using wet-layer and web-ext-translator might be an option.

Start using Typescript

Start using Typescript

With Svelte:

• Using Typescript with Svelte
• Vite with Svelte and Typescript

On tests:

• Lusito/webextension-polyfill-ts: This is a TypeScript ready "wrapper" for the WebExtension browser API Polyfill by Mozilla
• Lusito/mockzilla-webextension: A mocking toolkit for web-extensions leveraging the power of TypeScript to enhance your jest experience.

Directory view: Drag and drop

Implement first version of drag and drop using Dragula:

• Individual bookmarks from right pane to left pane
• Selected bookmarks from right pane to left pane

Related issues: #16

Show when an URL is already saved

Show when a bookmark is already saved for the current URL.

Tasks:

• Show saved status on the extension icon

Directory view: Keyboard shortcuts

Keyboard shortcuts for select all, cut, copy paste and so on.

Self-explanatory UI for first time users

(Sorry for Bad english) When clicking on the Button right to the CategoryField it should open the DropDownMenu longer, where we can see all the Folders, because now i can not see all my Folders.

There are Solutions to this how to do it:
-On clicking to the Button a new windows opens instead the Dropdown menu.
-Make the Dropdown menu longer that we can see the subfolders too

Maybe I can help you when i have instelled the Development Tools.

Directory view: Implement search, filtering and sorting

Implement search, filtering and sorting options for categories and bookmarks on left and right pane respectively.

Left side:

• Implement filtering (search)
• Implement sorting (by title, created, modified)?

Right side:

• Implement filtering / search
• Implement sorting (by title, url, created, modified)

Show recently accessed categories on the popup

Chrome shows recent categories on the popup, and even preselects the last modified category.

• Show recent categories on the popup
• Preselect the last modified category

Clean up styles

Use different styles sheets for directory and popup, but also import common styles into them.

• Convert sass styles into scss
• Extract common styles from popup and directory styles
• Check and clean up component styles (see list below)
• Clean up separate stylesheets

Following components have styles in them – check them:

• CategorySelector
• CategoryList
• Directory
• Category
• Popup
• DirectoryHeader
• Favicon
• Bookmark
• BookmarkPath
• BookmarkForm

Implement Javascript based resizing of the left pane

Chrome bookmarks uses Javascript to make resizing the left pane easy.
Implement similar functionality.

Wrong data in popup

Installed 0.3.7, first time trying spellbook. Folder search is awesome :)

Often (but I can not reproduce 100% of the time) the wrong URL is present on screen in the add bookmark widget (e.g. about:blank instead of the address in the address bar), sometimes the wrong title is present too (and wrong URL).

The wrong title is less frequent.

To "fix" it I end up closing tab, reopening and copy.pasting URL which works on about the 3rd try.

I do have a lot of tabs in case that helps

Create new subcategories from the popup

The add bookmark popups for Chrome and Firefox provide a way to create new categories.
Implement Pinterest-like or similar functionality for this.

Setup browser testing with Puppeteer

• Test the popup as a web page
• Define locale for popup
• Implement some meaningful tests

Remove all empty bookmark categories

Add a feature on options page to remove empty bookmark categories

Validate the popup for empty category on submit

Validate the popup for empty category on submit.
Currently the popup just closes now without saving the bookmark.

Organise existing bookmarks from the popup

Enable modifying and organising existing bookmarks from the popup.

Investigate using Rambda

Investigate using Rambda

• Try replacing Ramda with Rambda
• Test if there are speed differences or other benefits

Firefox bookmark tags

Thanks again for this extension. If it wasn't so useful I wouldn't be bothering you with two ideas to expand upon its functionality! This is much more specific as I don't know if the bookmark tags in Firefox are widely used, and Chrome doesn't have this feature at all. But I am assuming users of your extension will be very keen bookmark users and more likely to use it than most.

It'd be nice to be able to set bookmark tags. I am currently doing this by just clicking the blue star in the address bar which is perfectly adequate, but I think this would be an appropriate addition and streamline workflow for those of us who do use tags.

Drag and drop bookmarks in and out of the browser window

Use Dragula for drag and drop.

Make sure that default keyboard works

The default keyboard shortcut does not work in Firefox 88 on Linux. Change it to something that works on:

• Different operating systems (Command vs. Ctrl)
• Different Firefox and Chrome versions

These shortcuts might work:

• Ctrl-B on Mac (Chrome and Firefox)
• Ctrl-Alt-B on Linux & Windows (Chrome and Firefox)

Or just use Ctrl-B everywhere?

Other options:

• Cmd-Opt-S / Ctrl-Alt-S
• Cmd-Ctrl-B / Ctrl-Alt-B

Notes:

• Ctrl-Alt modifiers can’t be used (on Chrome at least) because they conflict with AltGr
• Alt and Alt-Shift will open menus on Linux and Windows

Investigation:

Chrome on Mac:

• Cmd-B: Current default
• Ctrl-Opt-S: Available
• Cmd-Opt-S: Let's set it, but does not work
• Cmd-Ctrl-D: Dictionary

Firefox on Mac:

• MacCtrl-B: Available (and current default, MacCtrl means Ctrl)
• Cmd-B: Bookmarks sidebar
• Cmd-Shift-B: Bookmarks bar

Firefox on Linux:

• Ctrl-Alt-D: Available
• Ctrl-Alt-B: Available
• Ctrl-E: Available
• Ctrl-B: Bookmarks sidebar
• Ctrl-Shift-B: Bookmarks bar
• Ctrl-Shift-S: Firefox screenshots
• Ctrl-Alt-S: Saka (is this default?)
• Alt-S: Opens menu Sivuhistoria

Add options page

Version 0.4.0 will have options page, and some useful cleanup and privacy features in there.

Navigate to subcategories by clicking the category path

• Navigate to parent by clicking the category path on the popup when adding bookmark
• Navigate to parent categories when exploring from popup

Move logic out of components

Tasks:

• Move logic from components into lib
• Make operations async
• Move some logic to the background page (high effort, questionable impact)

Consider:

• Does the logic apply to all tabs or just the current one?
• Not all things need to happen on background page – code might be more clear without indirections
• Aim is to make component code just represent the data and avoid blocking

Candidates to move to background:

• Searching
• Long lasting logic – all operations that take a while to complete
• Non async – possibly blocking operations

Use store for all bookmarks

Use store for all bookmarks

Questions:

• Preserve tree structure or make it flat?

Cancel promises on category search

Cancel promises with something like AbortController for fetch.

Bluebird offers cancellable promises and there are other options.

For custom implementation the structure of Promise cancellation could be something like delayedExecution even though this handles callback execution.

• Cancel Promises for WebExtension API requests when user changes the search or clears the search

Only get the current tab information after the popup is opened

Currently the current tab information is unneccessarily followed on the background page. Change this to only query the active tabs when the popup is opened.

This will also enable bookmarking multiple tabs at once, when the slider UI element for multiple bookmarks is implemented.

Fix adding subcategory with a bookmark on Firefox

This is a long standing bug, where adding a subcategory would not add the bookmark, but just the subcategory.

Strip tracking parameters from URLs

Strip tracking parameters from URLs

Specs

• Strip tracking parameters like UTM (Urchin tracking module), Facebook click id (fbclid) and Google click id from URLs, when the popup opens.
• Make it enabled by default, but enable disabling it through options.
• Help wanted! What other URL tracking parameters are there? Please comment.

More information:

• UTM parameters - Wikipedia
• Facebook adding “fbclid” parameter to outbound links | Hacker News
• Facebook now adds fbclid query string to URLs, busting CloudFlare's cache - Performance - Cloudflare Community
• What is fbclid? the new facebook parameter - Stack Overflow

Handle multiple bookmarks on popup

This enables saving multiple bookmarks or editing multiple existing bookmarks from the popup.
Get the selected tabs with query: {currentWindow: true, highlighted: true}.

Ideas:

• Move category on top then group URL and title, with URL being before title – this has the advantage of having category search on top, which can be used for searching existing bookmarks and showing the results below
• Enable bookmarking selected or all tabs on window at once
• Maybe implement carousel UI element for multiple bookmark results or just list the bookmarks with URL and titles grouped?
• When there are multiple bookmarks for an URL: show the URL only once and list individual bookmarks with title (and maybe parent category), but enable deleting, moving and editing each bookmark using buttons or some dropdown