Documentation Improvements (#12)

This PR makes a number of minor improvements, mostly related to visual
doc display:

- add escape key row
- Larkin doc display improvements
- bug in prefix `kind` labeling
- quick pick for extension installation
- update readme with examples

.vscodeignore

@@ -1,3 +1,4 @@
+images/**
 .vscode/**
 .vscode-test-web/**
 src/**

README.md

@@ -5,13 +5,6 @@
 [![codecov](https://codecov.io/gh/haberdashPI/vscode-master-key/graph/badge.svg?token=099XZY1KR9)](https://codecov.io/gh/haberdashPI/vscode-master-key)
 [![Code Style: Google](https://img.shields.io/badge/code%20style-google-blueviolet.svg)](https://github.com/google/gts)
 
-**TODO**: doc badges
-
-> [!WARNING]
-> 🚧 Master Key is still under construction. 🚧
->
-> The README is a WIP document that will eventually reflect the intended state for release 0.3.0 at which point this extension will be published to VSCode's extension marketplace. For now expect to find missing features, a variety of bugs and incomplete documentation.
-
 Master key helps you to learn, create and use powerful keybindings in [VSCode](https://code.visualstudio.com/).
 
 If you want to improve your text editing super powers in VSCode, Master Key might just be the tool for you.
@@ -26,87 +19,167 @@ The easiest way to get started is to activate the built-in keybindings that come
 
 ## Examples
 
-Master Key includes the following features:
+### Discoverability Features
+
+#### Visual documentation of keybindings
+
+Learn and review your bindings on a keyboard layout
+
+![example of visual docs](images/readme/visualdoc.jpg)
 
-**TODO**: insert example gif of each feature below
+#### Cheet sheet of keybindings
+
+Review your bindings in a cheet sheet organized by theme
+
+![example of cheet sheet](images/readme/cheatsheet.png)
+
+#### Keybinding hints
+
+See a quick pick palette of possible bindings for the current mode and prefix of keys already pressed.
+
+![example of palette](images/readme/palette.png)
+
+The example above shows the bindings available after pressing `m` in the Larkin keybinding
+set that is included with Master Key.
 
 ### Editing Features
 
-Here are some of the cool features that come with the built-in `Larkin` keybindings provided by Master Key with the help of [selection utilities](https://github.com/haberdashPI/vscode-selection-utilities). These bindings following in the footsteps of Vim, Kakaune and Helix.
+Here are some of the cool editing features that come with the built-in `Larkin` keybindings provided by Master Key with the help of [selection utilities](https://github.com/haberdashPI/vscode-selection-utilities). These bindings follow in the footsteps of Vim, Kakaune and Helix.
 
 #### Move by Object
 
-Select by word, line, block and more. Expand by indent, quotes and brackets.
+Select by word, line, paragraph and more.
+
+![examples of moving by word, line and paragraph](images/readme/selectby.webp)
+
+Expand by indent, quotes and brackets.
+
+![examples of expanding by indent, quote and brackets](images/readme/expandby.webp)
 
 Once you've selected the object, run commands to do stuff (e.g. delete/change/comment)
 
 #### Multi-Cursor Creation and Filtering
 
-Quickly create multiple selections by splitting selections or searching within selections.
-Filter out the ones you don't want either by some filter, or by manually picking out
-one or more you don't want.
+Quickly create multiple selections by splitting selections:
+
+![example of splitting a selection](images/readme/splitselect.webp)
+
+matching by word:
+
+![example of selecting by match](images/readme/selectmatch.webp)
+
+using saved selections:
+
+![example of using saved selections](images/readme/selectsaved.webp)
+
+Filter out the ones you don't want either by pattern:
+
+![example of filtering selections](images/readme/filterselect.webp)
+
+or manuall removal:
+
+![example of seelection deletion](images/readme/deleteselect.webp)
 
 #### Exchange Objects
 
 Swap selected objects with one another.
 
+![example of text exchange](images/readme/exchangetext.webp)
+
 #### Repeat Last Selection / Action
 
 Avoid lengthy key sequences by repeating the last action-related selection with "," and the last action with "."
 
+![example of repeating select/action](images/readme/repeat.webp)
+
 #### Record Commands
 
 Record longer command sequences and replay them.
 
+![example of recording key sequence](images/readme/record.webp)
+
 > [!NOTE]
-> Command command recording comes with a few limitations, refer to the documentation for details
+> Command recording comes with a few limitations, refer to the cheet sheet on Larkin macros for details
 
 #### Symmetric Insert
 
 Insert appropriate characters before and after each selection
 
-### Discoverability Features
-
-#### Visual documentation of keybindings
-
-Learn and review your bindings on a keyboard layout
-
-**NOTE**: demo the ability to toggle bindings on the keys
-
-#### Cheet sheet of keybindings
-
-Review your bindings in a cheet sheet organized by theme
-
-#### Keybinding hints
-
-See a quick pick palette of possible bindings for the current mode and prefix of keys already pressed
+![example of syminsert mode](images/readme/syminsert.webp)
 
 ### Keybinding Features
 
 > [!WARNING]
-> For the initial release of Master Key, the Keybinding Features are not yet well documented. The main goal of the 0.3.0 release was to make the default keybindings accessible to new users. See the roadmap section below for details. The finer points of implementing your own keybindings will require some digging into source code and/or asking questions in the discussions section of this repo.
+> For the initial release of Master Key, the Keybinding Features are not yet well documented. You can review the features when copying Larking to your own customization file. The main goal of the 0.3.0 release was to make the default keybindings accessible to new users. See the roadmap section below for details. The finer points of implementing your own keybindings will require some digging into source code and/or asking questions in the discussions section of this repo.
 
 When you create your own keybindings using Mater Key's special `.toml` keybinding format you get several powerful features that make it possible to easily create keybindings that would be difficult or impossible to implement without writing your own extension.
 
 #### Modal Bindings
 
 Your bindings can be modal—a special key (like escape) switches you to a different mode where all the keys on your keyboard can be used to issue commands specific to that mode.
 
+```toml
+[[bind]]
+key = "j"
+mode = "normal"
+command = ...
+```
+
 #### Parameteric Bindings
 
 Express an entire series of bindings using the `foreach` field.
 
+```toml
+[[bind]]
+path = "edit.count"
+foreach.num = ['{key: [0-9]}']
+name = "count {num}"
+key = "{num}"
+command = "master-key.updateCount"
+args.value = "{num}"
+```
+
 #### Stateful Bindings
 
 Update state with the `master-key.captureKeys`, `master-key.updateCount`, `master-key.setFlag` or `master-key.storeNamed` and then use this state in downstream commands using `computedArgs` instead of `args` in your keybinding.
 
+```toml
+[[bind]]
+name = "between pair"
+key = "m t"
+description = """
+Select between pairs of the same N characters
+"""
+command = "runCommands"
+
+[[bind.args.commands]]
+command = "master-key.captureKeys"
+args.acceptAfter = 1
+
+[[bind.args.commands]]
+command = "selection-utilities.selectBetween"
+computedArgs.str = "captured"
+args.inclusive = false
+```
+
 #### Record and Repeat Commands
 
 Master key records recent key presses, allowing you to create commands that quickly repeat a previous sequence using `master-key.replayFromHistory` or `master-key.pushHistoryToStack` and `master-key.replayFromStack`. You can disable key press recording by setting `master-key.maxCommandHistory` to 0 in your settings.
 
+```toml
+[[bind]]
+key = ";"
+name = "repeat motion"
+repeat = "count"
+command = "master-key.replayFromHistory"
+args.at = "commandHistory[i].path.startsWith('edit.motion') && commandHistory[i].name != 'repeat motion'"
+```
+
 #### Documented Bindings
 
 Of course, just like all of the built-in bindings in Master Key, you can document your bindings so that they show up legibly within the discoverability features above.
+The toml file is a literate document used to generate the textual documentation
+and all binding's names will show up in the visual documentation as appropriate.
 
 ## Customized Bindings
 
@@ -153,9 +226,10 @@ And of course, there are many existing editors that Master Key draws inspiration
 
 ## Developer Notes
 
-This repository relies on a working versions of `nvm` installed in bash and a npm version
-matching the version specified in `.nvmrc`. You can satisfy this requirement by copying and
-running the following in bash.
+This repository was designed to be worked with in unix-like environemtns. No effort to
+support development on Windows has been made. The setup relies on a working versions of
+`nvm` installed in bash and an npm version matching the version specified in `.nvmrc`. You
+can satisfy this requirement by copying and running the following in bash.
 
 ```sh
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash # install nvm
@@ -168,5 +242,5 @@ You can then install all dependencies for this project as follows:
 
 ```sh
 nvm use
-npm i
+npm ic
 ```

docview/style.css

@@ -111,6 +111,8 @@
 .key-length-1-75 { flex: 1.75; }
 .key-length-2-25 { flex: 2.25; }
 .key-length-5 { flex: 7; }
+.key-height-0-5 { height: calc(var(--key-height) / 2); }
+/* .key-height-1 { height: var(--key-height) } */
 
 .label {
     height: calc(var(--key-height) / 2 - var(--key-padding));
@@ -138,6 +140,10 @@
     border-top-left-radius: var(--key-radius);
 }
 
+.key.key-height-0-5 .label.bottom.no-top{
+    height: calc(var(--key-height) / 2 - 2*var(--key-padding))
+}
+
 .name {
     height: calc(var(--key-height) / 2 - var(--key-padding));
     font-size: 0.6rem;
@@ -167,3 +173,7 @@
     border-top: var(--key-border-width) solid var(--vscode-foreground);
     border-top-right-radius: var(--key-radius);
 }
+
+.key.key-height-0-5 .name.bottom.no-top{
+    height: calc(var(--key-height) / 2 - 2*var(--key-padding))
+}

notes.md

@@ -1,33 +1,22 @@
-## Optimization
-
-release 0.2.4
-
-observation: from what I can tell of profiling, it doesn't look like master key is consuming many CPU cycles at all; which is great!! no reason to work on this further
-
 ## More visual doc improvements
 
-IMPROVEMENT: show escape/function key row in the visual key doc
-
-release 0.2.2
+release 0.2.5
 
 - IMPROVEMENT: put some examples of cool features from `Larkin` in the README
 
-- IMPROVEMENT: use `getExtension` or some such on each required extension, and offer to
-  install if it fails (does this work for any extension? or does `activate` have to return
-  something)
-
-release 0.2.3
-
 by the end of this milestone I'm satisfied with the documentation features of the package for an initial release
 
 ## Binding Cleanup
 
-release 0.2.y
+release 0.2.6
 
 - feature: specify user-specific binding file, apart from activated keybindings
 - Split out any of the commands that are really custom for me that don't make sense to publish.
-- Pair down some of the required extensions.
-- Offer to install extensions? (maybe when a keybinding fails to run??)
+- Pair down some of the required extensions?
+
+## Trailing fixes
+
+Working with release 0.2.6 for a while and mark sure there aren't an bugs to fix
 
 ## Before VSCode publish
 
@@ -47,10 +36,18 @@ thoughts: things I must have to release:
 
 WHEN PUBLISHING: get this to work on both stores (the one from microsoft and the one that vscodium uses)
 
-## Additional test coverage
+## Stability / test coverage
 
 SMALL BUG: should 'esc' really be appended in the status bar since it cancels a prefix sequence... 🤔
 
+SMALL BUG: I think there are issues when synching across machines and handling
+storage of the keybindings
+
+NEW TESTS: keybindings
+- tests for running various binding commands
+- tests for selecting bindings
+- tests for selecting extensions?
+
 NEW TEST: store/restore named commands
 
 unit tests: edge cases with recording edits

package.json

@@ -3,7 +3,7 @@
   "displayName": "Master Key",
   "publisher": "haberdashPI",
   "description": "Master your keybindings with documentation, discoverability, modal bindings and expressive configuration",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "repository": {
     "url": "https://github.com/haberdashPi/vscode-master-key"
   },
@@ -40,6 +40,11 @@
         "category": "Master Key",
         "title": "Show Visual Documentation"
       },
+      {
+        "command": "master-key.installRequiredExtensions",
+        "category": "Master Key",
+        "title": "Install Extensions Required by Keybindings"
+      },
       {
         "command": "master-key.setVisualDocTopModifiers",
         "category": "Master Key",
@@ -280,9 +285,5 @@
     "yaml": "^2.3.4",
     "zod": "^3.22.4",
     "zod-validation-error": "^2.1.0"
-  },
-  "main": "./dist/desktop/extension.js",
-  "env": {
-    "NODE_ENV": "wdio"
   }
 }