/ikeysnail

iKeySnail provides fully-configurable hardware keyboard functionalities for web browsing on iOS (iPadOS)

Primary LanguageJavaScript

iKeySnail

iKeySnail provides fully-configurable hardware keyboard functionalities for web browsing on iOS (iPadOS).

The aim of this project is to provide { Vimium, Vimperator, Surfingkeys, KeySnail } for iOS. Currently, iKeySnail supports

  • Hardware keyboard supported web browsing
    • Emacs-like keybindings/functionalities
      • e.g., Ctrl-Space to set mark, Meta-w to copy the selected region, Ctrl-y to yank (paste) the clipboard text
    • Vim-like keybindings/functionalities
      • e.g., j/k/h/l/g/G to quickly scroll web pages
  • Link-hints (Hit-a-hint)
    • For clicking links without touching your iOS device screen
    • hints
  • Vertical tabs
    • We do support vertical tabs in iOS!
    • Setting config.TAB_VERTICAL = true makes tab orientations vertical
    • vtabs
  • Omnibar support
    • Work-in-progress, but we do support omnibar. By default, pressing o opens your bookmarks.
    • omnibar

Installation

You need JSBox (https://docs.xteko.com/#/en/) to run iKeySnail. After installing the JSBox, access either of

from iOS Safari. Then JSBox will install iKeySnail.

Manual Build

You can also manually build the package and install it in JSBox:

make package

then copy .output/ikeysnail.box to your JSBox app.

Usage

See strings/settings.js for available shortcuts.

Customization

Edit strings/settings.js.

Remote Settings

Tired of manually syncing your config across all of your devices?

Remote settings is your help. Prepare strings/settings.js that contains a variable config.REMOTE_CONFIG_URL and ikeysnail refers to the specified configuration on the remote server. For example

config.REMOTE_CONFIG_URL = "https://gist.githubusercontent.com/mooz/676f15e3814751df2e1b67e0b14f5f97/raw/ikeysnail_config.js";

works.

Defining / Customizing Keymap

We have four types of mode for key bindings.

  1. all-mode, whose keymaps are always active.
  2. view-mode, whose keymaps are active only if the cursor isn't on editable elements (akin to vim's normal mode).
  3. rich-mode, whose keymaps are active only if the cursor is on rich text editors (such as CodeMirror, Ace, Scrapbox, and contenteditable).
  4. edit-mode, whose keymaps are active only if the cursor is on input or textarea.

In each keymap, you can define a key's functionality in two ways:

  1. Remapping to different key (e.g., "ctrl-s": "meta-f"), and
  2. Invoke a JavaScript function (e.g., "ctrl-y": () => keysnail.paste()).

Defining a site

You can also define a site configuration in your settings.js. Configuration consists of

  • keymap -> keymap
  • style -> user css
  • alias -> alias
  • url -> url.

Examples are follows.

config.sites.push({
    alias: "Google",
    url: "https://www.google.com"
  });

  const GDOCS_KEYMAP = {
    rich: {
      "meta-f": keysnail.marked("alt-ArrowRight"),
      "meta-b": keysnail.marked("alt-ArrowLeft"),
      "meta-d": keysnail.marked("alt-Delete"),
      "ctrl-_": "ctrl-z",
      "ctrl-z": "meta-z",
      "ctrl-s": "ctrl-f"
    }
  };

  config.sites.push({
    alias: "Google Docs",
    url: "https://docs.google.com/",
    keymap: GDOCS_KEYMAP
  });

  config.sites.push({
    alias: "Google Docs (Slide)",
    url: "https://docs.google.com/presentation/",
    keymap: GDOCS_KEYMAP
  });

  config.sites.push({
    alias: "OverLeaf",
    url: "https://www.overleaf.com/project/",
    style: `
.toolbar { font-size: small !important; }
.entity { font-size: small !important; }
`
  });

  config.sites.push({
    alias: "Scrapbox",
    url: "https://scrapbox.io/",
    keymap: {
      rich: {
        "meta-f": keysnail.marked("alt-ArrowRight"),
        "meta-b": keysnail.marked("alt-ArrowLeft"),
        "ctrl-i": "ctrl-i",
        "ctrl-t": "ctrl-t"
      }
    },
    style: `
#editor {
  caret-color: transparent !important;
}
`
  });

Gifs

Omnibar

omnibar-mov

Link hints

linkhints-mov

Acknowledgements

Parts of iKeySnail are inspired by previous wonderful works (thanks to).

Releasing (for developers)

Building a package

make package

Releasing a package

make release