lively 0.11.0 → 0.13.0

data/lib/lively/application.rb

@@ -10,8 +10,18 @@ require "async/websocket/adapters/http"
 require_relative "pages/index"
 require_relative "hello_world"
 
+# @namespace
 module Lively
+	# Represents the main Lively application middleware.
+	# 
+	# This class serves as the entry point for Lively applications, handling both
+	# standard HTTP requests for the initial page load and WebSocket connections
+	# for live updates. It integrates with the Live framework to provide real-time
+	# interactive web applications.
 	class Application < Protocol::HTTP::Middleware
+		# Create a new application class configured for a specific Live view tag.
+		# @parameter tag [Class] The Live view class to use as the application body.
+		# @returns [Class] A new application class configured for the specified tag.
 		def self.[](tag)
 			klass = Class.new(self)
 			
@@ -26,36 +36,64 @@ module Lively
 			return klass
 		end
 		
+		# Get the default resolver for this application.
+		# @returns [Live::Resolver] A resolver configured to allow HelloWorld components.
 		def self.resolver
 			Live::Resolver.allow(HelloWorld)
 		end
 		
+		# Initialize a new Lively application.
+		# @parameter delegate [Protocol::HTTP::Middleware] The next middleware in the chain.
+		# @parameter resolver [Live::Resolver] The resolver for Live components.
 		def initialize(delegate, resolver: self.class.resolver)
 			super(delegate)
 			
 			@resolver = resolver
 		end
 		
+		# @attribute [Live::Resolver] The resolver for live components.
+		attr :resolver
+		
+		# @attribute [Protocol::HTTP::Middleware] The delegate middleware for request handling.
+		attr :delegate
+		
+		# Handle a WebSocket connection for live updates.
+		# @parameter connection [Async::WebSocket::Connection] The WebSocket connection.
 		def live(connection)
 			Live::Page.new(@resolver).run(connection)
 		end
 		
+		# Get the title for this application.
+		# @returns [String] The class name of this application.
 		def title
 			self.class.name
 		end
 		
+		# Create the body content for this application.
+		# @parameter **options [Hash] Additional options to pass to the body constructor.
+		# @returns [HelloWorld] A new HelloWorld instance.
 		def body(...)
 			HelloWorld.new(...)
 		end
 		
+		# Create the index page for this application.
+		# @parameter **options [Hash] Additional options to pass to the index constructor.
+		# @returns [Pages::Index] A new index page instance.
 		def index(...)
 			Pages::Index.new(title: self.title, body: self.body(...))
 		end
 		
+		# Handle a standard HTTP request.
+		# @parameter request [Protocol::HTTP::Request] The incoming HTTP request.
+		# @parameter **options [Hash] Additional options.
+		# @returns [Protocol::HTTP::Response] The HTTP response with the rendered page.
 		def handle(request, ...)
 			return Protocol::HTTP::Response[200, [], [self.index(...).call]]
 		end
 		
+		# Process an incoming HTTP request.
+		# @parameter request [Protocol::HTTP::Request] The incoming HTTP request.
+		# @returns [Protocol::HTTP::Response] The appropriate response for the request.
 		def call(request)
 			if request.path == "/live"
 				return Async::WebSocket::Adapters::HTTP.open(request, &self.method(:live)) || Protocol::HTTP::Response[400]

data/lib/lively/assets.rb

@@ -5,8 +5,15 @@
 
 require "protocol/http/middleware"
 require "protocol/http/body/file"
+require "console"
 
 module Lively
+	# Represents an HTTP middleware for serving static assets.
+	# 
+	# This middleware serves static files from a configured root directory with
+	# appropriate content type headers and caching controls. It supports a wide
+	# range of web file formats including HTML, CSS, JavaScript, images, fonts,
+	# audio, video, and WebAssembly files.
 	class Assets < Protocol::HTTP::Middleware
 		DEFAULT_CACHE_CONTROL = "no-store, no-cache, must-revalidate, max-age=0"
 		
@@ -14,24 +21,53 @@ module Lively
 			".html" => "text/html",
 			".css" => "text/css",
 			".js" => "application/javascript",
+			".mjs" => "application/javascript",
+			".json" => "application/json",
 			".png" => "image/png",
+			".jpg" => "image/jpeg",
 			".jpeg" => "image/jpeg",
 			".gif" => "image/gif",
+			".webp" => "image/webp",
+			".svg" => "image/svg+xml",
+			".ico" => "image/x-icon",
 			".mp3" => "audio/mpeg",
 			".wav" => "audio/wav",
+			".ogg" => "audio/ogg",
+			".mp4" => "video/mp4",
+			".webm" => "video/webm",
+			".ttf" => "font/ttf",
+			".woff" => "font/woff",
+			".woff2" => "font/woff2",
+			".wasm" => "application/wasm",
 		}
 		
 		PUBLIC_ROOT = File.expand_path("../../public", __dir__)
 		
+		# Initialize a new assets middleware instance.
+		# @parameter delegate [Protocol::HTTP::Middleware] The next middleware in the chain.
+		# @parameter root [String] The root directory path for serving assets.
+		# @parameter content_types [Hash] Mapping of file extensions to MIME types.
+		# @parameter cache_control [String] Cache control header value for responses.
 		def initialize(delegate, root: PUBLIC_ROOT, content_types: DEFAULT_CONTENT_TYPES, cache_control: DEFAULT_CACHE_CONTROL)
 			super(delegate)
 			
-			@root = root
+			@root = File.expand_path(root)
 			
 			@content_types = content_types
 			@cache_control = cache_control
 		end
 		
+		# @attribute [String] The absolute path to the root directory for serving assets.
+		attr :root
+		
+		# @attribute [Hash] Mapping of file extensions to content types.
+		attr :content_types
+		
+		# @attribute [String] Cache control header value for asset responses.
+		attr :cache_control
+		
+		# Freeze this middleware instance and all its configuration.
+		# @returns [Assets] Returns self for method chaining.
 		def freeze
 			return self if frozen?
 			
@@ -42,29 +78,45 @@ module Lively
 			super
 		end
 		
-		def response_for(path, content_type)
-			headers = [
-				["content-type", content_type],
-				["cache-control", @cache_control],
-			]
+		# Generate an HTTP response for the given file path.
+		# @parameter path [String] The absolute file path to serve.
+		# @returns [Protocol::HTTP::Response] HTTP response with file content or error.
+		def response_for(path)
+			extension = File.extname(path)
 			
-			return Protocol::HTTP::Response[200, headers, Protocol::HTTP::Body::File.open(path)]
+			if content_type = @content_types[extension]
+				headers = [
+					["content-type", content_type],
+					["cache-control", @cache_control],
+				]
+				
+				return Protocol::HTTP::Response[200, headers, Protocol::HTTP::Body::File.open(path)]
+			else
+				Console.warn(self, "Unsupported media type!", path: path)
+				return Protocol::HTTP::Response[415, [["content-type", "text/plain"]], "Unsupported media type: #{extension.inspect}!"]
+			end
 		end
 		
+		# Expand a relative path to an absolute path within the asset root.
+		# @parameter path [String] The relative path to expand.
+		# @returns [String | Nil] The absolute path if valid, `nil` if the file doesn't exist.
 		def expand_path(path)
-			File.realpath(File.join(@root, path))
+			root = File.realpath(@root)
+			path = File.realpath(File.join(@root, path))
+			
+			if path.start_with?(root) && File.file?(path)
+				return path
+			end
 		rescue Errno::ENOENT
 			nil
 		end
 		
+		# Handle an incoming HTTP request.
+		# @parameter request [Protocol::HTTP::Request] The incoming HTTP request.
+		# @returns [Protocol::HTTP::Response] The HTTP response for the asset or delegates to next middleware.
 		def call(request)
 			if path = expand_path(request.path)
-				extension = File.extname(path)
-				content_type = @content_types[extension]
-				
-				if path.start_with?(@root) && File.exist?(path) && content_type
-					return response_for(path, content_type)
-				end
+				return response_for(path)
 			end
 			
 			super

data/lib/lively/environment/application.rb

@@ -1,35 +1,50 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 require_relative "../application"
 require_relative "../assets"
 
 require "falcon/environment/server"
 
+# @namespace
 module Lively
+	# @namespace
 	module Environment
+		# Represents the environment configuration for a Lively application server.
+		# 
+		# This module provides server configuration including URL binding, process count,
+		# application class resolution, and middleware stack setup. It integrates with
+		# Falcon's server environment to provide a complete hosting solution.
 		module Application
 			include Falcon::Environment::Server
 			
-			# def url
-			# 	"http://localhost:9292"
-			# end
+			# Get the server URL for this application.
+			# @returns [String] The base URL where the server will be accessible.
+			def url
+				"http://localhost:9292"
+			end
 			
+			# Get the number of server processes to run.
+			# @returns [Integer] The number of worker processes.
 			def count
 				1
 			end
 			
+			# Resolve the application class to use.
+			# @returns [Class] The application class, either user-defined or default.
 			def application
 				if Object.const_defined?(:Application)
-					::Application
+					Object.const_get(:Application)
 				else
 					Console.warn(self, "No Application class defined, using default.")
 					::Lively::Application
 				end
 			end
 			
+			# Build the middleware stack for this application.
+			# @returns [Protocol::HTTP::Middleware] The complete middleware stack.
 			def middleware
 				::Protocol::HTTP::Middleware.build do |builder|
 					builder.use Lively::Assets, root: File.expand_path("public", self.root)

data/lib/lively/hello_world.rb

@@ -3,14 +3,27 @@
 # Released under the MIT License.
 # Copyright, 2024-2025, by Samuel Williams.
 
+# @namespace
 module Lively
+	# Represents a "Hello World" Live view component.
+	# 
+	# This component displays a simple greeting message with a real-time clock
+	# that updates every second. It serves as a demonstration of Lively's
+	# live update capabilities and provides basic usage instructions.
 	class HelloWorld < Live::View
+		# Initialize a new HelloWorld view.
+		# @parameter **options [Hash] Additional options passed to the parent view.
 		def initialize(...)
 			super
 			
 			@clock = nil
 		end
 		
+		# @attribute [Async::Task | Nil] The background task that updates the view periodically.
+		attr :clock
+		
+		# Bind this view to a page and start the update clock.
+		# @parameter page [Live::Page] The page this view is bound to.
 		def bind(page)
 			super
 			
@@ -23,12 +36,15 @@ module Lively
 			end
 		end
 		
+		# Close this view and stop the update clock.
 		def close
 			@clock&.stop
 			
 			super
 		end
 		
+		# Render this view as HTML.
+		# @parameter builder [Live::Builder] The HTML builder for constructing the view.
 		def render(builder)
 			builder.tag(:h1) do
 				builder.text("Hello, I'm Lively!")

data/lib/lively/pages/index.rb

@@ -5,10 +5,20 @@
 
 require "xrb/template"
 
+# @namespace
 module Lively
+	# @namespace
 	module Pages
+		# Represents the main index page for a Lively application.
+		# 
+		# This class renders the initial HTML page that users see when they visit
+		# a Lively application. It uses an XRB template to generate the page structure
+		# and embeds the Live view component for dynamic content.
 		class Index
-			def initialize(title: "Lively", body: "Hello World")
+			# Initialize a new index page.
+			# @parameter title [String] The title of the page.
+			# @parameter body [Object] The body content of the page.
+			def initialize(title: "Lively", body: nil)
 				@title = title
 				@body = body
 				
@@ -16,9 +26,17 @@ module Lively
 				@template = XRB::Template.load_file(path)
 			end
 			
+			# @attribute [String] The title of the page.
 			attr :title
+			
+			# @attribute [Object] The body content of the page.
 			attr :body
 			
+			# @attribute [XRB::Template] The XRB template for rendering the page.
+			attr :template
+			
+			# Render this page to a string.
+			# @returns [String] The rendered HTML for this page.
 			def call
 				@template.to_string(self)
 			end

data/lib/lively/pages/index.xrb

@@ -14,15 +14,13 @@
 		{
 			"imports": {
 				"live": "/_components/@socketry/live/Live.js",
+				"live-audio": "/_components/@socketry/live-audio/Live/Audio.js",
 				"morphdom": "/_components/morphdom/morphdom-esm.js"
 			}
 		}
 		</script>
 		
-		<script type="module">
-			import {Live} from 'live';
-			window.live = Live.start();
-		</script>
+		<script type="module" src="/application.js"></script>
 	</head>
 	
 	<body>

data/lib/lively/version.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
+# @namespace
 module Lively
-	VERSION = "0.11.0"
+	VERSION = "0.13.0"
 end

data/public/_components/@socketry/live/Live.js

@@ -1,5 +1,33 @@
 import morphdom from 'morphdom';
 
+// ViewElement - Base class for Live.js custom elements
+export class ViewElement extends HTMLElement {
+	static observedAttributes = [];
+	static connectedElements = new Set();
+	
+	connectedCallback() {
+		if (!this.id) {
+			this.id = crypto.randomUUID();
+		}
+		
+		ViewElement.connectedElements.add(this);
+		
+		const window = this.ownerDocument.defaultView;
+		if (window && window.live) {
+			window.live.bind(this);
+		}
+	}
+	
+	disconnectedCallback() {
+		ViewElement.connectedElements.delete(this);
+		
+		const window = this.ownerDocument.defaultView;
+		if (window && window.live) {
+			window.live.unbind(this);
+		}
+	}
+}
+
 export class Live {
 	#window;
 	#document;
@@ -10,13 +38,20 @@ export class Live {
 	
 	static start(options = {}) {
 		let window = options.window || globalThis;
+		if (window.live) throw new Error("Live.js is already started!");
+		
 		let path = options.path || 'live'
 		let base = options.base || window.location.href;
 		
 		let url = new URL(path, base);
 		url.protocol = url.protocol.replace('http', 'ws');
 		
-		return new this(window, url);
+		window.live = new this(window, url);
+		if (!window.customElements.get('live-view')) {
+			window.customElements.define('live-view', ViewElement);
+		}
+		
+		return window.live;
 	}
 	
 	constructor(window, url) {
@@ -34,43 +69,6 @@ export class Live {
 		this.#document.addEventListener("visibilitychange", () => this.#handleVisibilityChange());
 		
 		this.#handleVisibilityChange();
-		
-		const elementNodeType = this.#window.Node.ELEMENT_NODE;
-		
-		// Create a MutationObserver to watch for removed nodes
-		this.observer = new this.#window.MutationObserver((mutationsList, observer) => {
-			for (let mutation of mutationsList) {
-				if (mutation.type === 'childList') {
-					for (let node of mutation.removedNodes) {
-						if (node.nodeType !== elementNodeType) continue;
-						
-						if (node.classList?.contains('live')) {
-							this.#unbind(node);
-						}
-						
-						// Unbind any child nodes:
-						for (let child of node.getElementsByClassName('live')) {
-							this.#unbind(child);
-						}
-					}
-					
-					for (let node of mutation.addedNodes) {
-						if (node.nodeType !== elementNodeType) continue;
-						
-						if (node.classList.contains('live')) {
-							this.#bind(node);
-						}
-						
-						// Bind any child nodes:
-						for (let child of node.getElementsByClassName('live')) {
-							this.#bind(child);
-						}
-					}
-				}
-			}
-		});
-		
-		this.observer.observe(this.#document.body, {childList: true, subtree: true});
 	}
 	
 	// -- Connection Handling --
@@ -167,23 +165,19 @@ export class Live {
 		}
 	}
 	
-	#bind(element) {
-		console.log("bind", element.id, element.dataset);
-		
+	bind(element) {
 		this.#send(JSON.stringify(['bind', element.id, element.dataset]));
 	}
-	
-	#unbind(element) {
-		console.log("unbind", element.id, element.dataset);
-		
+
+	unbind(element) {
 		if (this.#server) {
 			this.#send(JSON.stringify(['unbind', element.id]));
 		}
 	}
-	
+
 	#attach() {
-		for (let node of this.#document.getElementsByClassName('live')) {
-			this.#bind(node);
+		for (let element of ViewElement.connectedElements) {
+			this.bind(element);
 		}
 	}
 	

data/public/_components/@socketry/live/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@socketry/live",
   "type": "module",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Live HTML tags for Ruby.",
   "main": "Live.js",
+  "files": [
+    "Live.js"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/socketry/live-js.git"