Improve docs (#51)

* fix typos

* fix typos in ts

* Update README.md

typos readme

* add instructions for hook api

* fix context doc

* improve docs

* improve component doc

Author: LinuxDoku

README.md

@@ -335,8 +335,9 @@ See the [chat example](https://github.com/jfyne/live-examples/tree/main/chat) fo
 
 ### Hooks
 
-Hooks take the following form. They allow additional javscript to be during a
-page lifecycle.
+Hooks take the following form. They allow additional javascript to hook into the live lifecycle.
+These should be used to implement custom behavior and bind additional events which are not supported
+out of the box.
 
 [embedmd]:# (web/src/interop.ts)
 ```ts
@@ -422,10 +423,25 @@ See the [chat example](https://github.com/jfyne/live-examples/tree/main/chat) fo
 
 ### Integrating with your app
 
-There are two ways to inegrate javascript into your applications. The first is the simplest, using the built
+There are two ways to integrate javascript into your applications. The first is the simplest, using the built
 in javascript handler. This includes client side code to initialise the live handler and automatically looks for
 hooks at `window.Hooks`. All of the examples use this method.
 
+To add a custom hook register it before including the `live.js` file.
+```javascript
+window.Hooks = window.Hooks || {};
+window.Hooks['my-hook'] = {
+	mount: function() {
+		// ...
+	}
+};
+```
+
+Use the `live-hook` attribute to wire the hook with live.
+```html
+<div live-hook="my-hook"></div>
+```
+
 See the [chat example](https://github.com/jfyne/live-examples/tree/main/chat) for usage.
 
 The second method is suited for more complex apps, there is a companion package published on npm. The version
@@ -520,7 +536,7 @@ selects file(s), the file metadata can be validated with a helper function.
 Reactive entries - Uploads are populated in the `.Uploads` template context. Entries automatically respond
 to progress and errors.
 
-### Entry validataion
+### Entry validation
 
 File selection triggers the usual form change event and there is a helper function to validate the uploads. 
 Use `live.ValidateUploads` to validate the incoming files. Any validation errors will be available in the `.Uploads`

context.go

@@ -32,7 +32,7 @@ func contextWithWriter(ctx context.Context, w http.ResponseWriter) context.Conte
 	return context.WithValue(ctx, writerKey, w)
 }
 
-// Request pulls out an initiating request from a context.
+// Writer pulls out a response writer from a context.
 func Writer(ctx context.Context) http.ResponseWriter {
 	data := ctx.Value(writerKey)
 	w, ok := data.(http.ResponseWriter)

engine.go

@@ -260,7 +260,7 @@ func (e *BaseEngine) sockets() []Socket {
 }
 
 // hasSocket check a socket is there error if it isn't connected or
-// doensn't exist.
+// doesn't exist.
 func (e *BaseEngine) hasSocket(s Socket) error {
 	e.socketsMu.Lock()
 	defer e.socketsMu.Unlock()

event.go

@@ -8,11 +8,11 @@ import (
 type EventConfig func(e *Event) error
 
 const (
-	// EventError indicates an error has occured.
+	// EventError indicates an error has occurred.
 	EventError = "err"
 	// EventPatch a patch event containing a diff.
 	EventPatch = "patch"
-	// EventAck sent when an event is ackknowledged.
+	// EventAck sent when an event is acknowledged.
 	EventAck = "ack"
 	// EventConnect sent as soon as the server accepts the
 	// WS connection.

http.go

@@ -56,7 +56,7 @@ func (h *HttpEngine) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	// Check if we are going to upgrade to a webscoket.
+	// Check if we are going to upgrade to a websocket.
 	upgrade := false
 	for _, header := range r.Header["Upgrade"] {
 		if header == "websocket" {
@@ -77,7 +77,7 @@ func (h *HttpEngine) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Upgrade to the webscoket version.
+	// Upgrade to the websocket version.
 	h.serveWS(ctx, w, r)
 }
 

page/component.go

@@ -30,10 +30,16 @@ type SelfHandler func(ctx context.Context, data interface{}) (interface{}, error
 // ComponentConstructor a func for creating a new component.
 type ComponentConstructor func(ctx context.Context, h live.Handler, s live.Socket) (*Component, error)
 
-// Component a self contained component on the page.
+// Component is a self contained component on the page. Components can be reused accross the application
+// or used to compose complex interfaces by splitting events handlers and render logic into
+// smaller pieces.
+//
+// Remember to use a unique ID and use the Event function which scopes the event-name
+// to trigger the event in the right component.
 type Component struct {
 	// ID identifies the component on the page. This should be something stable, so that during the mount
 	// it can be found again by the socket.
+	// When reusing the same component this ID should be unique to avoid conflicts.
 	ID string
 
 	// Handler a reference to the host handler.

page/configuration.go

@@ -20,7 +20,7 @@ func WithRegister(fn RegisterHandler) ComponentConfig {
 	}
 }
 
-// WithMount set a mounnt handler on the component.
+// WithMount set a mount handler on the component.
 func WithMount(fn MountHandler) ComponentConfig {
 	return func(c *Component) error {
 		c.Mount = fn

pubsub.go

@@ -54,15 +54,15 @@ func (p *PubSub) Subscribe(topic string, h Engine) {
 	})
 }
 
-// Receice a message from the transport.
+// Recieve a message from the transport.
 func (p *PubSub) Recieve(topic string, msg Event) {
 	ctx := context.Background()
 	for _, node := range p.handlers[topic] {
 		node.self(ctx, nil, msg)
 	}
 }
 
-// TransportMessage a userful container to send live events.
+// TransportMessage a useful container to send live events.
 type TransportMessage struct {
 	Topic string
 	Msg   Event

socket.go

@@ -28,7 +28,7 @@ type Socket interface {
 	// socket.
 	Assigns() interface{}
 	// Assign set data to this socket. This will happen automatically
-	// if you return data from and `EventHander`.
+	// if you return data from an `EventHander`.
 	Assign(data interface{})
 	// Connected returns true if this socket is connected via the websocket.
 	Connected() bool
@@ -96,7 +96,7 @@ func NewBaseSocket(s Session, e Engine, connected bool) *BaseSocket {
 	}
 }
 
-// ID generate a unique ID for this socket.
+// ID generates a unique ID for this socket.
 func (s *BaseSocket) ID() SocketID {
 	if s.id == "" {
 		s.id = SocketID(NewID())
@@ -112,8 +112,8 @@ func (s *BaseSocket) Assigns() interface{} {
 	return s.data
 }
 
-// Assign set data to this socket. This will happen automatically
-// if you return data from and `EventHander`.
+// Assign sets data to this socket. This will happen automatically
+// if you return data from an `EventHander`.
 func (s *BaseSocket) Assign(data interface{}) {
 	s.dataMu.Lock()
 	defer s.dataMu.Unlock()
@@ -125,15 +125,15 @@ func (s *BaseSocket) Connected() bool {
 	return s.connected
 }
 
-// Self send an event to this socket itself. Will be handled in the
+// Self sends an event to this socket itself. Will be handled in the
 // handlers HandleSelf function.
 func (s *BaseSocket) Self(ctx context.Context, event string, data interface{}) error {
 	msg := Event{T: event, SelfData: data}
 	s.engine.self(ctx, s, msg)
 	return nil
 }
 
-// Broadcast send an event to all sockets on this same engine.
+// Broadcast sends an event to all sockets on this same engine.
 func (s *BaseSocket) Broadcast(event string, data interface{}) error {
 	return s.engine.Broadcast(event, data)
 }
@@ -175,17 +175,17 @@ func (s *BaseSocket) AllowUploads(config *UploadConfig) {
 	s.uploadConfigs = append(s.uploadConfigs, config)
 }
 
-// UploadConfigs return the configs for this socket.
+// UploadConfigs returns the configs for this socket.
 func (s *BaseSocket) UploadConfigs() []*UploadConfig {
 	return s.uploadConfigs
 }
 
-// Uploads return the sockets uploads.
+// Uploads returns the sockets uploads.
 func (s *BaseSocket) Uploads() UploadContext {
 	return s.uploads
 }
 
-// AssignUpload set uploads to this socket.
+// AssignUpload sets uploads to this socket.
 func (s *BaseSocket) AssignUpload(config string, upload *Upload) {
 	if s.uploads == nil {
 		s.uploads = map[string][]*Upload{}
@@ -202,12 +202,12 @@ func (s *BaseSocket) AssignUpload(config string, upload *Upload) {
 	s.uploads[config] = append(s.uploads[config], upload)
 }
 
-// ClearUploads clear this sockets upload map.
+// ClearUploads clears this sockets upload map.
 func (s *BaseSocket) ClearUploads() {
 	s.uploads = map[string][]*Upload{}
 }
 
-// ClearUpload clear a specific upload from this socket.
+// ClearUpload clears a specific upload from this socket.
 func (s *BaseSocket) ClearUpload(config string, upload *Upload) {
 	if s.uploads == nil {
 		s.uploads = map[string][]*Upload{}
@@ -223,15 +223,22 @@ func (s *BaseSocket) ClearUpload(config string, upload *Upload) {
 	}
 }
 
+// LastRender returns the last render result of this socket.
 func (s *BaseSocket) LatestRender() *html.Node {
 	return s.currentRender
 }
+
+// UpdateRender replaces the last render result of this socket.
 func (s *BaseSocket) UpdateRender(render *html.Node) {
 	s.currentRender = render
 }
+
+// Session returns the session of this socket.
 func (s *BaseSocket) Session() Session {
 	return s.session
 }
+
+// Messages returns a channel of event messages sent and received by this socket.
 func (s *BaseSocket) Messages() chan Event {
 	return s.msgs
 }

web/src/forms.ts

@@ -118,13 +118,13 @@ export class Forms {
                     values[this.upKey][key].push(fi);
                     break;
                 default:
-                    // If the key doesn exist set it.
+                    // If the key doesn't exist set it.
                     if (!Reflect.has(values, key)) {
                         values[key] = value;
                         return;
                     }
                     // If it already exists that means this needs to become
-                    // and array.
+                    // an array.
                     if (!Array.isArray(values[key])) {
                         values[key] = [values[key]];
                     }

web/src/interop.ts

@@ -54,7 +54,7 @@ export interface Hook {
 }
 
 /**
- * The DOM management interace. This allows external JS libraries to
+ * The DOM management interface. This allows external JS libraries to
  * interop with Live.
  */
 export interface DOM {