live 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f33999c1164c25bd9fccfac8d7be846b6ad536ae04da0302b450662a7db1624f
-  data.tar.gz: 0bbd2f3b7b06819b9ae5cb8b057277a1885fe7d44598238a46d21704eb62173c
+  metadata.gz: a836ae392c3fb38c18c6317e94786d0ad943d01afe1486026333148531bb681b
+  data.tar.gz: e5f9ecb4911b74fbecad809d068d8a076d8cd4d93c8d015f9d709ccb737c5b76
 SHA512:
-  metadata.gz: a5bcd37c979d0155cd70b822f7959ae7d97661c7652f2e945cc9b9ff6ff4a099600894f8348b0b135abeb90dd1156e724ed2b063b68c2c908c5823240b41af3c
-  data.tar.gz: 68aae390d5d46ca5e81d4f333a40d3db1e9fbf8394d41600576dace4b0a2bd2df5c94ab8795cbdd156bab01e07ecc0b372d84853c5e99c965481b4fb1f9a0ce6
+  metadata.gz: b896681bad42c651744baaef703204ef112e226446ce3ca530453f4247053f0dde771897d898a45b0a2c5ff64e3291e0e1a856d8e05041dcc5424d28e093aed1
+  data.tar.gz: bb53aa53e263bcbc03ae22dc8280c21cdc388e261430ac9e70533f6a551a360341bbffa255a0271cc1e88cd4d7c1d2757b185fd057b75d0e224920d2205d74ff

data/lib/live/element.rb

@@ -23,7 +23,10 @@
 require 'json'
 
 module Live
+	# Represents a single dynamic content area on the page.
 	class Element
+		# @parameter id [String] The unique identifier within the page.
+		# @parameter data [Hash] The data associated with the element, typically stored as `data-` attributes.
 		def initialize(id, **data)
 			@id = id
 			@data = data
@@ -32,8 +35,11 @@ module Live
 			@page = nil
 		end
 		
+		# The unique id within the bound page.
 		attr :id
 		
+		# Generate a JavaScript string which forwards the specified event to the server.
+		# @parameter details [Hash] The details associated with the forwarded event.
 		def forward(details = nil)
 			if details
 				"live.forward(#{JSON.dump(@id)}, event, #{JSON.dump(details)})"
@@ -42,13 +48,25 @@ module Live
 			end
 		end
 		
+		# Bind this tag to a dynamically updating page.
+		# @parameter page [Live::Page]
 		def bind(page)
 			@page = page
 		end
 		
-		def handle(event, details)
+		def close
+			@page = nil
+		end
+		
+		# Handle a client event, typically as triggered by {#forward}.
+		# @parameter event [String] The type of the event.
+		# @parameter details [Hash] The associated details if any.
+		def handle(event, details = nil)
 		end
 		
+		# Enqueue a remote procedure call to the currently bound page.
+		# @parameter method [Symbol] The name of the remote functio to invoke.
+		# @parameter arguments [Array]
 		def rpc(method, arguments)
 			# This update might not be sent right away. Therefore, mutable arguments may be serialized to JSON at a later time (or never). This could be a race condition:
 			@page.updates.enqueue([method, arguments])

data/lib/live/page.rb

@@ -27,7 +27,9 @@ require 'async'
 require 'async/queue'
 
 module Live
+	# Represents a connected client page with bound dynamic content areas.
 	class Page
+		# @parameter resolver [Live::Resolver] Used to resolve client-side elements to server-side element instances.
 		def initialize(resolver)
 			@resolver = resolver
 			
@@ -35,18 +37,30 @@ module Live
 			@updates = Async::Queue.new
 		end
 		
+		# The queue of outstanding events to be sent to the client.
 		attr :updates
 		
+		# Bind a client-side element to a server side element.
+		# @parameter element [Live::Element] The element to bind.
 		def bind(element)
 			@elements[element.id] = element
 			
 			element.bind(self)
 		end
 		
+		# Resolve a client-side element to a server side instance.
+		# @parameter id [String] The unique identifier within the page.
+		# @parameter data [Hash] The data associated with the element, typically stored as `data-` attributes.
 		def resolve(id, data)
 			@resolver.call(id, data)
 		end
 		
+		# Handle an event from the client. If the element could not be found, it is silently ignored.
+		# @parameter id [String] The unique identifier of the element which forwarded the event.
+		# @parameter event [String] The type of the event.
+		# @parameter details [Hash] The associated details if any.
+		# @returns [Object] The result of the element handler, if the element was found.
+		# @returns [Nil] If the element could not be found.
 		def handle(id, event, details)
 			if element = @elements[id]
 				return element.handle(event, details)
@@ -57,39 +71,42 @@ module Live
 			return nil
 		end
 		
-		def run(connection)
-			reader_task = start_reader(connection)
-			
-			while update = @updates.dequeue
-				Console.logger.debug(self, "Sending update:", update)
-				
-				connection.write(update)
-				connection.flush if @updates.empty?
+		def close
+			@elements.each do |id, element|
+				element.close
 			end
-		ensure
-			reader_task&.stop
 		end
 		
-		private
-		
-		def start_reader(connection)
-			Async do
-				while message = connection.read
-					Console.logger.debug(self, "Reading message:", message)
+		# Run the event handling loop with the given websocket connection.
+		# @parameter connection [Async::WebSocket::Connection]
+		def run(connection)
+			queue_task = Async do
+				while update = @updates.dequeue
+					Console.logger.debug(self, "Sending update:", update)
 					
-					if id = message[:bind] and data = message[:data]
-						if element = self.resolve(id, data)
-							self.bind(element)
-						else
-							Console.logger.warn(self, "Could not resolve element:", message)
-						end
-					elsif id = message[:id]
-						self.handle(id, message[:event], message[:details])
+					connection.write(update)
+					connection.flush if @updates.empty?
+				end
+			end
+			
+			while message = connection.read
+				Console.logger.debug(self, "Reading message:", message)
+				
+				if id = message[:bind] and data = message[:data]
+					if element = self.resolve(id, data)
+						self.bind(element)
 					else
-						Console.logger.warn(self, "Unhandled message:", message)
+						Console.logger.warn(self, "Could not resolve element:", message)
 					end
+				elsif id = message[:id]
+					self.handle(id, message[:event], message[:details])
+				else
+					Console.logger.warn(self, "Unhandled message:", message)
 				end
 			end
+		ensure
+			self.close
+			queue_task&.stop
 		end
 	end
 end

data/lib/live/resolver.rb

@@ -34,6 +34,7 @@ module Live
 			@allowed = {}
 		end
 		
+		# @attribute [Hash(String, Class)] A map of allowed class names.
 		attr :allowed
 		
 		def freeze

data/lib/live/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Live
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/live/view.rb

@@ -24,22 +24,31 @@ require_relative 'element'
 require 'trenni/builder'
 
 module Live
+	# Represents a single division of content on the page an provides helpers for rendering the content.
 	class View < Element
+		# Replace the content of the client-side element by rendering this view.
 		def replace!
 			rpc(:replace, [@id, self.to_html])
 		end
 		
-		def append!(node)
-			rpc(:append, [@id, node.to_html])
+		# Append to the content of the client-side element by appending the specified element.
+		# @parameter node [Live::Element] The element to append.
+		def append!(element)
+			rpc(:append, [@id, element.to_html])
 		end
 		
-		def prepend!(node)
-			rpc(:prepend, [@id, node.to_html])
+		# Prepend to the content of the client-side element by appending the specified element.
+		# @parameter node [Live::Element] The element to prepend.
+		def prepend!(element)
+			rpc(:prepend, [@id, element.to_html])
 		end
 		
+		# Render the element.
+		# @parameter builder [Trenni::Builder] The HTML builder.
 		def render(builder)
 		end
 		
+		# @returns [Object] The generated HTML.
 		def to_html
 			Trenni::Builder.fragment do |builder|
 				builder.tag :div, id: @id, class: 'live', data: @data do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: live
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-19 00:00:00.000000000 Z
+date: 2021-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: trenni