docs: update docs

docs/README.md

@@ -16,8 +16,8 @@ The aim of this project is to enable web developers to add support for typing no
 
 **What does Keywrite do?**
 
-1. It allows you to map certain keyboard inputs to characters, which you define in a keyboard layout configuration file.
-1. It binds with web input controls to add multi-lingual typing to your website
+1. It allows you to map keyboard inputs to symbols, which you define in a keyboard layout configuration file.
+1. It binds with web input controls to add multi-lingual typing to your web application
 
 **Things you can build with Keywrite**
 

docs/advanced_usage.md

@@ -1,3 +1,9 @@
-# Advanced Features
+# Advanced Usage
 
 ## Extending the core package
+
+By extending the exported class from `@keywrite/core` you can add
+app-specific logic. The most important method in the core class would be the
+`write` method. This method takes in a character and resolves it into a special
+symbol as per the layout specification and returns the symbol and replacement
+state (if previous character needs to be replaced with the new symbol).

docs/basic_usage.md

@@ -49,9 +49,7 @@ myKeywriteInstance.on = true;
 
 It is possible to add more than one keyboard layout to an instance. This could
 be useful if you want users to pick from a selection of
-input methods.
-
-multiple layout definitions can be added during initialization.
+input methods. Multiple layout definitions can be added during initialization.
 
 ```javascript
 // keyboard layout definitions
@@ -68,7 +66,7 @@ const myKeywriteInstance = new KeywriteWeb(document.querySelector('input'), {
 });
 ```
 
-You switch between the layouts by setting the `current` value in the instance to
+You can switch between the layouts by setting the `current` value in the instance to
 the key name of the layout you want.
 
 ```javascript

docs/examples.md

@@ -0,0 +1 @@
+# Examples

docs/keyboard_layout.md

@@ -4,9 +4,191 @@ A keyboard layout maps keyboard inputs to symbols. It allows us to define key co
 produce a certain symbol. It is generally a JavaScript object with an
 input character, an output value or a next value.
 
+A simple keyboard layouts looks something like this:
+
+```javascript
+const myLayout = {
+    a: { value: '∀', next: null },
+    e: {
+        value: '∈',
+        next: {
+            e: {
+                value: '∉',
+                next: null,
+            },
+        },
+    },
+};
+```
+
+In the above layout, the `a` keyboard input is mapped to the `∀` symbol.
+Pressing `e` will output `∈`, pressing `e` again will output `∉`.
+
+## Components of a keyboard layout
+
 A keyboard layout has two basic components:
 
-1. Symbol map
-1. Layout
+1. **SymbolMap:** object with a `value` and `next` keys.
+1. **KeyboardLayout:** object mapping an input key to a symbol map object
+
+Keyboard layout is a nested structure of these two components. Lets see this
+components in more detail.
+
+The interface for `SymbolMap` and `KeyboardLayout` is shown below:
+
+```typescript
+interface SymbolMap {
+    value: string | null;
+    next: KeyboardLayout | null;
+}
+
+type KeyboardLayout = Record<string, SymbolMap>;
+```
+
+`value` represents the output symbol and `next` represents the next keyboard
+layout definition.
+
+From our previous example, the symbol map for the `a` key is this:
+
+```javascript
+const symbolMapA = { value: '∀', next: null };
+```
+
+The keyboard layout is as follows:
+
+```javascript
+const layoutA = { a: { value: '∀', next: null } };
+```
+
+`layoutA` is a valid layout that you can provide to a Keywrite instance.
+But to build a more complete keyboard layout, you can add additional input key
+and symbol map pairs.
+
+```javascript
+const layoutWithMoreInputKeys = {
+    a: { value: '∀', next: null },
+    b: { value: '⋈', next: null },
+    c: { value: '⊂', next: null },
+    d: { value: '∂', next: null },
+};
+```
+
+Our inputs and outputs for the above layout are as follows:
+
+| Input Key | Output Symbol |
+| --------- | ------------- |
+| `a`       | ∀             |
+| `b`       | ⋈             |
+| `c`       | ⊂             |
+| `d`       | ∂             |
+
+We would also need to map certain combination of key inputs to a single character.
+We can do that by nesting additional layouts in the symbol map `next` field.
+
+```javascript
+const myLayout = {
+    a: {
+        value: '∀',
+        next: null,
+    },
+    b: {
+        value: '⋈',
+        next: {
+            l: {
+                value: '⋉',
+                next: null,
+            },
+            r: {
+                value: '⋊',
+                next: null,
+            },
+        },
+    },
+    c: {
+        value: '⊂',
+        next: {
+            n: {
+                value: '⊄',
+                next: {
+                    u: {
+                        value: '⊈',
+                        next: null,
+                    },
+                },
+            },
+            u: {
+                value: '⊆',
+                next: {
+                    n: {
+                        value: '⊈',
+                        next: null,
+                    },
+                },
+            },
+            l: {
+                value: '⊃',
+                next: {
+                    n: {
+                        value: '⊅',
+                        next: {
+                            u: {
+                                value: '⊉',
+                                next: null,
+                            },
+                        },
+                    },
+                    u: {
+                        value: '⊇',
+                        next: {
+                            n: {
+                                value: '⊉',
+                                next: null,
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    d: { value: '∂', next: null },
+};
+```
+
+Now our input output table looks like this:
+
+| Input Key             | Output Symbol |
+| --------------------- | ------------- |
+| `a`                   | ∀             |
+| `b`                   | ⋈             |
+| `b` + `l`             | ⋉             |
+| `b` + `r`             | ⋊             |
+| `c`                   | ⊂             |
+| `c` + `u`             | ⊆             |
+| `c` + `u` + `n`       | ⊈             |
+| `c` + `n`             | ⊄             |
+| `c` + `n` + `u`       | ⊈             |
+| `c` + `l`             | ⊃             |
+| `c` + `l` + `n`       | ⊅             |
+| `c` + `l` + `n` + `u` | ⊉             |
+| `c` + `l` + `u`       | ⊇             |
+| `c` + `u`             | ⊇             |
+| `c` + `u` + `n`       | ⊉             |
+| `d`                   | ∂             |
+
+The complete code is shown below:
+
+<iframe src="https://codesandbox.io/embed/keywrite-layouts-example-149ml?fontsize=14&hidenavigation=1&theme=dark"
+     style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+     title="keywrite-layouts-example"
+     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+   ></iframe>
+
+## Creating keyboard layouts
+
+Keyboard layout definitions are simple json objects. It is possible to manually write a layout definition that will work with Keywrite, but a better way would be to use the [Layout Generator](layout_generator.md).
+
+## Pre-made layouts
 
-Symbol map is an object with a `value` and `next` keys. Value specifies
+Some layouts are avaliable pre-made and you add simply add them to your project.
+A list of all available layouts can be found [here](pre_made_layouts.md)

docs/layout_generator.md

@@ -0,0 +1 @@
+# Examples

docs/packages.md

@@ -0,0 +1 @@
+# Packages

docs/pre_made_layouts.md

@@ -0,0 +1 @@
+# Pre-made Layouts