Merge branch 'release/v1.0.0'

.luacov

@@ -4,6 +4,7 @@ return {
     reportfile = 'luacov.report.out',
     runreport = true,
     exclude = {
+        'docs',
         'deps',
         'dist',
         'luacov$',

README.md

@@ -4,49 +4,49 @@
 
 ### What's that?
 
-Ki introduces a novel approach to automating macOS. Inspired by text editing models found in [vi](https://en.wikipedia.org/wiki/Vi#Interface) and [Kakoune](http://kakoune.org/why-kakoune/why-kakoune.html), Ki enables composable commands to execute desktop tasks and see whether modal shortcuts can be effective in the macOS environment.
+Ki introduces a novel approach to automating macOS. Inspired by the [vi](https://en.wikipedia.org/wiki/Vi#Interface) text editor, Ki enables composable commands to execute desktop tasks to see whether it can be effective in automating the desktop environment.
 
-By entering `normal` mode with the command and escape key <kbd>⌘⎋</kbd>, an extensive set of command chains become available to achieve various workflows:
-- <kbd>⌘⎋</kbd><kbd>⌘e</kbd><kbd>s</kbd> - enter `entity` mode <kbd>⌘e</kbd> and activate or focus the **Safari** <kbd>s</kbd> application
-- <kbd>⌘⎋</kbd><kbd>⌘a</kbd><kbd>Space</kbd><kbd>s</kbd> - enter `action` mode <kbd>⌘a</kbd> and toggle media <kbd>Space</kbd> playing in the frontmost **Safari** <kbd>s</kbd> window and tab
+From the default resting `desktop` state, enter `normal` mode with the default hotkey <kbd>⌘⎋</kbd> (Command and Escape), where an extensive set of command chains become available to achieve various workflows:
+- <kbd>⌘⎋</kbd><kbd>⌘e</kbd><kbd>s</kbd> - enter `entity` mode <kbd>⌘e</kbd> and open or focus the **Safari** <kbd>s</kbd> application
+- <kbd>⌘⎋</kbd><kbd>⌘a</kbd><kbd>Space</kbd><kbd>s</kbd> - enter `action` mode <kbd>⌘a</kbd> and toggle media <kbd>Space</kbd> in the frontmost **Safari** <kbd>s</kbd> window
 - <kbd>⌘⎋</kbd><kbd>⌘s</kbd><kbd>s</kbd><kbd>⌘3</kbd> - enter `select` mode <kbd>⌘s</kbd> and focus a specific **Safari** <kbd>s</kbd> tab, the third one <kbd>⌘3</kbd> from the left
 
 With those semantics in mind, we can intuit other "sentences" if we know other entities <kbd>g</kbd>, <kbd>m</kbd>, and <kbd>⇧s</kbd>:
-- <kbd>⌘⎋</kbd><kbd>⌘e</kbd><kbd>g</kbd> - enter `entity` mode <kbd>⌘e</kbd> and activate or focus the **Google Chrome** <kbd>g</kbd> application
+- <kbd>⌘⎋</kbd><kbd>⌘e</kbd><kbd>g</kbd> - enter `entity` mode <kbd>⌘e</kbd> and open or focus the **Google Chrome** <kbd>g</kbd> application
 - <kbd>⌘⎋</kbd><kbd>⌘a</kbd><kbd>Space</kbd><kbd>⇧s</kbd> - enter `action` mode <kbd>⌘a</kbd> and toggle the current song <kbd>Space</kbd> in the **Spotify** <kbd>⇧s</kbd> application
 - <kbd>⌘⎋</kbd><kbd>⌘s</kbd><kbd>m</kbd><kbd>⌘3</kbd> - enter `select` mode <kbd>⌘s</kbd> and focus a specific **Messages** <kbd>m</kbd> conversation, the third one <kbd>⌘3</kbd> from the top
 
-Shortcuts can be chained even further to compose more complex workflows for certain applications:
-- <kbd>⌘⎋</kbd><kbd>⌘a</kbd><kbd>d</kbd><kbd>⌘s</kbd><kbd>s</kbd><kbd>⌘2</kbd> - enter `action` mode <kbd>⌘a</kbd> to add a bookmark <kbd>d</kbd>, and enter `select` mode <kbd>⌘s</kbd> to target the specific **Safari** <kbd>s</kbd> tab, the second one <kbd>⌘2</kbd> from the left
-- <kbd>⌘⎋</kbd><kbd>⌘a</kbd><kbd>Space</kbd><kbd>⌘s</kbd><kbd>g</kbd><kbd>⌘4</kbd> - enter `action` mode <kbd>⌘a</kbd> to toggle some media <kbd>Space</kbd>, and enter `select` mode <kbd>⌘s</kbd> to target the specific **Google Chrome** <kbd>g</kbd> tab, the fourth one <kbd>⌘4</kbd> from the left
+For certain applications, shortcuts can be chained even further to compose more complex workflows:
+- <kbd>⌘⎋</kbd><kbd>⌘a</kbd><kbd>Space</kbd><kbd>⌘s</kbd><kbd>g</kbd><kbd>⌘4</kbd> - enter `action` mode <kbd>⌘a</kbd> to toggle media <kbd>Space</kbd>, and enter `select` mode <kbd>⌘s</kbd> to target the specific **Google Chrome** <kbd>g</kbd> tab, the fourth one <kbd>⌘4</kbd> from the left
+- <kbd>⌘⎋</kbd><kbd>⌘a</kbd><kbd>w</kbd><kbd>⌘s</kbd><kbd>s</kbd><kbd>⌘2</kbd> - enter `action` mode <kbd>⌘a</kbd> to close a tab <kbd>w</kbd>, and enter `select` mode <kbd>⌘s</kbd> to target the specific **Safari** <kbd>s</kbd> tab, the second one <kbd>⌘2</kbd> from the left
 
-To see all Ki shortcuts, you can activate a **Cheatsheet** entity with <kbd>⌘⎋</kbd><kbd>⌘e</kbd><kbd>?</kbd>. To see all shortcuts for actions that an entity implements, you can apply a "Show Cheatsheet" action with <kbd>⌘⎋</kbd><kbd>⌘a</kbd><kbd>?</kbd><kbd>(entity)</kbd>.
+To see Ki shortcuts, you can activate the **Cheatsheet** with <kbd>⌘⎋</kbd><kbd>⌘e</kbd><kbd>?</kbd>. To see all shortcuts for actions that an entity implements, you can show its **Cheatsheet** with <kbd>⌘⎋</kbd><kbd>⌘a</kbd><kbd>?</kbd><kbd>(entity)</kbd>.
 
 ## Installation
 
-Install [Hammerspoon](https://github.com/Hammerspoon/hammerspoon/releases/latest) and extract [Ki.spoon](https://github.com/andweeb/ki/releases/latest) to `~/.hammerspoon/Spoons`.
+Install [Hammerspoon](http://www.hammerspoon.org) and extract [Ki.spoon.zip](https://github.com/andweeb/ki/releases/latest) to `~/.hammerspoon/Spoons`.
 
 ## Usage and Configuration
 
 Load, configure, and start the plugin in `~/.hammerspoon/init.lua`:
 
 ```lua
-hs.loadSpoon('Ki')            -- initialize the plugin
-spoon.Ki.workflows = {...}    -- remap keybindings and add custom workflows, modes, and other various configurations
-spoon.Ki:start()              -- enable keyboard shortcuts
+hs.loadSpoon('Ki')                 -- initialize the plugin
+spoon.Ki.workflowEvents = {...}    -- configure `spoon.Ki` here
+spoon.Ki:start()                   -- enable keyboard shortcuts
 ```
 
-Nearly everything in Ki is customizable! Documentation for all configurables can be found [here](https://andweeb.github.io/ki/html/Ki.html).
+Nearly everything in Ki is customizable! API documentation can be found [here](https://andweeb.github.io/ki/html/Ki.html) and usage examples [here](docs/usage-examples).
 
 ## Development
 
 ```bash
 # Setup
 make deps      # install local luarocks dependencies necessary for Ki
-make dev-deps  # install global test and lint dependencies and install pip requirements for the docs generator
+make dev-deps  # install global luarocks dev dependencies and pip requirements for the docs generator
 
 # Development
-# (prefix the target names below with `watch-` to monitor for file changes using `fswatch`)
+# Prefix the target names below with `watch-` to monitor for file changes using `fswatch`
 make docs      # generate source documentation
 make lint      # run linter on source and spec files
 make test      # run busted unit tests and generate coverage files

docs/html/Application.html

@@ -1,7 +1,7 @@
 <html>
     <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-    <title>Hammerspoon docs: Application</title>
+    <title>Ki docs: Application</title>
     <style type="text/css">
       a { text-decoration: none; }
       a:hover { text-decoration: underline; }
@@ -30,6 +30,7 @@ <h3>API Overview</h3>
             <li><a href="#focus">focus</a></li>
             <li><a href="#getApplication">getApplication</a></li>
             <li><a href="#getMenuItemList">getMenuItemList</a></li>
+            <li><a href="#getSelectionItems">getSelectionItems</a></li>
             <li><a href="#initialize">initialize</a></li>
             <li><a href="#toggleFullScreen">toggleFullScreen</a></li>
           </ul>
@@ -104,11 +105,11 @@ <h5><a href="#focus">focus</a></h5>
               </tr>
               <tr>
                 <th>Description</th>
-                <td><p>Focuses the application</p>
+                <td><p>Activates an application or focuses a specific application window or tab</p>
 <p>Parameters:</p>
 <ul>
 <li><code>app</code> - the <a href="https://www.hammerspoon.org/docs/hs.application.html"><code>hs.application</code></a> object</li>
-<li><code>choice</code> - an optional choice object</li>
+<li><code>choice</code> - an optional <a href="https://www.hammerspoon.org/docs/hs.chooser.html#choices">choice</a> object, each with a <code>windowId</code> field and (optional) <code>tabIndex</code> field</li>
 </ul>
 <p>Returns:</p>
 <ul>
@@ -169,6 +170,33 @@ <h5><a href="#getMenuItemList">getMenuItemList</a></h5>
 <ul>
 <li>A list of <a href="https://www.hammerspoon.org/docs/hs.application.html#getMenuItems">menu items</a> or <code>nil</code></li>
 </ul>
+</td>
+              </tr>
+            </table>
+          </section>
+          <section id="getSelectionItems">
+            <a name="//apple_ref/cpp/Method/getSelectionItems" class="dashAnchor"></a>
+            <h5><a href="#getSelectionItems">getSelectionItems</a></h5>
+            <table>
+              <tr>
+                <th>Signature</th>
+                <td><code>Application:getSelectionItems()</code></td>
+              </tr>
+              <tr>
+                <th>Type</th>
+                <td>Method</td>
+              </tr>
+              <tr>
+                <th>Description</th>
+                <td><p>Returns choice objects containing application window information.</p>
+<p>Parameters:</p>
+<ul>
+<li>None</li>
+</ul>
+<p>Returns:</p>
+<ul>
+<li>A list of <a href="https://www.hammerspoon.org/docs/hs.chooser.html#choices">choice</a> objects</li>
+</ul>
 </td>
               </tr>
             </table>

docs/html/Cheatsheet.html

@@ -1,7 +1,7 @@
 <html>
     <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-    <title>Hammerspoon docs: Cheatsheet</title>
+    <title>Ki docs: Cheatsheet</title>
     <style type="text/css">
       a { text-decoration: none; }
       a:hover { text-decoration: underline; }

docs/html/Defaults.html

@@ -1,7 +1,7 @@
 <html>
     <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-    <title>Hammerspoon docs: Defaults</title>
+    <title>Ki docs: Defaults</title>
     <style type="text/css">
       a { text-decoration: none; }
       a:hover { text-decoration: underline; }

docs/html/Entity.html

@@ -1,7 +1,7 @@
 <html>
     <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-    <title>Hammerspoon docs: Entity</title>
+    <title>Ki docs: Entity</title>
     <style type="text/css">
       a { text-decoration: none; }
       a:hover { text-decoration: underline; }