add api reference docs (#61)

README.md

@@ -1,6 +1,7 @@
 # Fir
 
-[![Go Reference](https://pkg.go.dev/badge/github.com/livefir/fir.svg)](https://pkg.go.dev/github.com/livefir/fir) 
+[![Go API Reference](https://pkg.go.dev/badge/github.com/livefir/fir.svg)](https://pkg.go.dev/github.com/livefir/fir)
+[![Alpine API Reference](https://img.shields.io/badge/alpine_plugin-reference-blue)](./alpinejs-plugin/README.md) 
 [![npm version](https://badge.fury.io/js/@livefir%2Ffir.svg)](https://badge.fury.io/js/@livefir%2Ffir)
 
 **A Go toolkit to build reactive web interfaces using: [Go](https://go.dev/), [html/template](https://pkg.go.dev/html/template) and [alpinejs](https://alpinejs.dev/).**

alpinejs-plugin/README.md

@@ -18,4 +18,85 @@ The plugin can be included as a script tag before the `alpine.js` include.
 ```
 
 
- See [example](https://github.com/livefir/fir#example).
+ See [example](https://github.com/livefir/fir#example).
+
+
+ ## API
+
+ The plugin provides event handlers [custom magic and directives](https://alpinejs.dev/advanced/extending).
+
+
+ ### Event handlers
+
+ Fir depends on alpinejs custom event handlers to update the DOM. Event handlers are of the syntax:
+
+ `<x-on:@>:fir:event-id:event-state<ok|error|pending|done>::template-name<optional>`
+
+ For e.g,
+
+ ```html
+ <div @fir:create-todo:ok::todo="$fir.prependEl()">
+    {{ range .todos }}
+        {{ block "todo" . }}
+
+        {{end}}
+    {{end}}
+</div>
+ ```
+
+ The expression `@fir:create-todo:ok::todo` means that if `create-todo`event handler returns with a non-error response then re-render the template named `todo`and send the html to the browser. The event handler utility function `$fir.prependEl()`picks the returned html from `event.detail.html`and prepends it to the current element. For a full list of utiliy functions see section [Magics](#magics)
+
+
+The `::template-name` binding is optional. It is useful for situations where one needs to re-use a template out-of-band like the example above.
+
+Fir automatically extracts a template from any element which contains html/template actions.
+
+For e.g.
+
+```html
+<p @fir:create-todo:error="$fir.replace()">
+    {{ fir.Error "create-todo.text" }}
+</p>
+```
+
+Here Fir automatically extracts a template out of the content of `p`tag. Under the hood, this is how it looks like:
+
+```html
+<p @fir:create-todo:error::fir-kxkccoas8d9="$fir.replace()">
+    {{ fir.Error "create-todo.text" }}
+</p>
+```
+
+#### Event states
+
+- ok: when [OnEvent](https://pkg.go.dev/github.com/livefir/fir@main#OnEvent) handler returns a non-error response.
+- error: when OnEvent returns an error response.
+- pending: client-only for loader states. triggered before the Event is sent to the server.
+- done: client-only for loader states. triggered on both ok and error response from the server.
+
+
+### Directives
+
+`x-fir-mutation-observer` implements the https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver as an
+alpine directive. It allows you to observe changes to the DOM and react to them.
+
+e.g.
+
+```html
+x-fir-mutation-observer.child-list.subtree="if ($el.children.length === 0) { empty = true } else { empty = false }"
+```
+
+### Magics
+
+See [api.md](api.md)
+
+
+### Modifiers
+
+`.nohtml` modifier tells the server to not send the resultant html to the client. This is useful in cases like these:
+
+```html
+ @fir:create:ok.nohtml="$el.reset()"
+
+ @fir:delete:ok.nohtml="$fir.removeEl()"
+```

alpinejs-plugin/api.md

@@ -0,0 +1,123 @@
+## Functions
+
+<dl>
+<dt><a href="#replace">replace()</a> ⇒ <code>function</code></dt>
+<dd><p>Replaces the content of an element with the HTML generated from the provided event.</p>
+</dd>
+<dt><a href="#replaceEl">replaceEl()</a> ⇒ <code>function</code></dt>
+<dd><p>Replaces the element with the new HTML content generated by the event.</p>
+</dd>
+<dt><a href="#appendEl">appendEl()</a> ⇒ <code>function</code></dt>
+<dd><p>Appends an element to the DOM.</p>
+</dd>
+<dt><a href="#prependEl">prependEl()</a> ⇒ <code>function</code></dt>
+<dd><p>Prepends an element to the DOM.</p>
+</dd>
+<dt><a href="#afterEl">afterEl()</a> ⇒ <code>function</code></dt>
+<dd><p>Inserts an element after the current element.</p>
+</dd>
+<dt><a href="#beforeEl">beforeEl()</a> ⇒ <code>function</code></dt>
+<dd><p>Inserts an element before the current element.</p>
+</dd>
+<dt><a href="#removeEl">removeEl()</a> ⇒ <code>function</code></dt>
+<dd><p>Removes the element from the DOM.</p>
+</dd>
+<dt><a href="#removeParentEl">removeParentEl(event)</a></dt>
+<dd><p>Removes the parent element of the specified element.</p>
+</dd>
+<dt><a href="#emit">emit(id, params, target)</a> ⇒ <code>function</code></dt>
+<dd><p>Emits an event with the specified ID, parameters, and target.</p>
+</dd>
+<dt><a href="#submit">submit(opts)</a> ⇒ <code>void</code></dt>
+<dd><p>Submits a form or emits an event to the server.</p>
+</dd>
+</dl>
+
+<a name="replace"></a>
+
+## replace() ⇒ <code>function</code>
+Replaces the content of an element with the HTML generated from the provided event.
+
+**Kind**: global function  
+**Returns**: <code>function</code> - - A function that accepts an event and replaces the element's content.  
+<a name="replaceEl"></a>
+
+## replaceEl() ⇒ <code>function</code>
+Replaces the element with the new HTML content generated by the event.
+
+**Kind**: global function  
+**Returns**: <code>function</code> - - A function that accepts an event and replaces the element with the new HTML content.  
+<a name="appendEl"></a>
+
+## appendEl() ⇒ <code>function</code>
+Appends an element to the DOM.
+
+**Kind**: global function  
+**Returns**: <code>function</code> - - The event listener function.  
+<a name="prependEl"></a>
+
+## prependEl() ⇒ <code>function</code>
+Prepends an element to the DOM.
+
+**Kind**: global function  
+**Returns**: <code>function</code> - - The event listener function.  
+<a name="afterEl"></a>
+
+## afterEl() ⇒ <code>function</code>
+Inserts an element after the current element.
+
+**Kind**: global function  
+**Returns**: <code>function</code> - - A function that accepts an event and calls the `afterElement` function.  
+<a name="beforeEl"></a>
+
+## beforeEl() ⇒ <code>function</code>
+Inserts an element before the current element.
+
+**Kind**: global function  
+**Returns**: <code>function</code> - - The function that inserts an element before the specified element.  
+<a name="removeEl"></a>
+
+## removeEl() ⇒ <code>function</code>
+Removes the element from the DOM.
+
+**Kind**: global function  
+**Returns**: <code>function</code> - The event handler function that removes the element.  
+<a name="removeParentEl"></a>
+
+## removeParentEl(event)
+Removes the parent element of the specified element.
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>Event</code> | The event object. |
+
+<a name="emit"></a>
+
+## emit(id, params, target) ⇒ <code>function</code>
+Emits an event with the specified ID, parameters, and target.
+
+**Kind**: global function  
+**Returns**: <code>function</code> - - A function that can be called to emit the event.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| id | <code>string</code> | The ID of the event. |
+| params | <code>object</code> | The parameters to be passed with the event. |
+| target | <code>string</code> | The target of the event. |
+
+<a name="submit"></a>
+
+## submit(opts) ⇒ <code>void</code>
+Submits a form or emits an event to the server.
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| opts | <code>Object</code> | Options for the submission. |
+| opts.event | <code>string</code> | The event ID to be emitted. |
+| opts.params | <code>Object</code> | The parameters to be sent with the submission. |
+| opts.target | <code>string</code> | The target element for the response. |
+