docs: update README regarding state, events and array methods

readme.md

@@ -8,52 +8,116 @@
 
 ## Setting State
 
-Set state with 
+`State` are variables that changes the UI or the DOM that uses it when they get updated. 
 
-Set variables with vanilla JS
-```
+### Setting Initial State
+
+You can set the initial state of the variables using vanilla JS:
+
+```html
 <script type="text/javascript">
   firstName = "Tony"
   lastName = "Ennis"
 </script>
 ```
 
-#### Syncing the dom with your state
-- :value
-  - Set the value of a form input to a js variable which stays in sync when that variable changes. 
+### Syncing the DOM with your state
+
+These are the following attributes that you can use to sync the DOM with your state:
+
+- `:value`
+  - Set the value of a form input to a JS variable which stays in sync when that variable changes. 
   - Works with the following input types: text, textarea, select, datepicker.
-- :class
-  - Set the class of any dom element based on the value of a js variable.
-- :text
-  - Set the text of any dom element based on the value of a js variable.
+- `:class`
+  - Set the class of any DOM element based on the value of a js variable.
+- `:text`
+  - Set the text of any DOM element based on the value of a js variable.
 
-#### Statements
-- :each - loop through an array and render a template for each item
+```html
+<script type="text/javascript">
+  firstName = "Tony"
+</script>
+
+<input type="text" :change="firstName = this.value" />
 
-#### Variable Methods
+<!-- The innerText of this paragraph changes based on the firstName variable --> 
+<p :text="firstName"></p>
+```
 
-##### Array
-- search
-- toggle
-- add 
-- remove
-- first
-- last
+### Triggering DOM Updates / Re-renders
 
-## Tips
-- Use `this.value` to get the value of the current form
+A DOM update or a re-render happens when the state variable is re-assigned:
+
+```html
+<input type="text" :change="firstName = this.value" />
+<!-- the re-assignment of firstName will trigger DOM updates that uses that variable -->
+```
+
+## Events
+
+You can create, use, and update state variables inside DOM events.
 
 ### Native Events
-- All native events are supported. You can use them like this:
+
+All native events are supported. You can use them like this:
 
 ```html
 <button :click="console.log('click')">Click Me</button>
-<div :load="activeTab = 'My Accounts'"></div>
 ```
 
-- For `:load` events, it will fire immediately after MiniJS is initialized.
+You can access the current element in the event via `this`:
 
-#### Custom Events
-- :clickout
-- :change
-- :enter
+```html
+<button :click="this.classList.toggle('active')">Click Me</button>
+
+<input :change="this.value = this.value.toUpperCase()" />
+```
+
+### Custom Events
+
+These are the events added in by MiniJS:
+
+- `:clickout` - This will trigger when the user clicks outside of the current element
+- `:change` - This will trigger when the user changes the value of a form input
+- `:enter` - This will trigger when the user presses the enter key
+- `:keyup.up` - This will trigger when the user presses the up arrow key
+- `:keyup.down` - This will trigger when the user presses the down arrow key
+- `:keyup.left` - This will trigger when the user presses the left arrow key
+- `:keyup.right` - This will trigger when the user presses the right arrow key
+
+
+## Statements
+
+- :each - loop through an array and render a template for each item
+
+## Variable Methods
+
+MiniJS adds some commonly-used custom methods to variables.
+
+### Array
+
+Here are the custom array methods which are available for you to use:
+
+- `first` - returns the first item in the array.
+  Usage: `array.first()`
+- `last` - returns the last item in the array.
+  Usage: `array.last()`
+- `search` - returns an array of items that match the query.
+  Usage: `array.search('query')`
+- `toggle`
+  Usage: `array.toggle('item')`
+- `add` - adds an item to the array if it doesn't exist.
+  Usage: `array.add('item')`
+- `remove` - removes an item from the array if it exists.
+  Usage: `array.remove('item')`
+
+To trigger a re-render you need to update the variable:
+
+```js
+// Will not trigger a re-render
+filteredTags.remove("Chocolates")
+
+// Will trigger a re-render due to re-assignment of the
+// filteredTags variable.
+filteredTags = filteredTags.remove("Chocolates")
+```