web_ruby_ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 390ac580582694ff163f766967f0b90aab3d3df6c70a8306a192f58e0889d0d1
+  data.tar.gz: 781d6b5303602c16d22564abe89b7c82c666fff7656e550195a1b27b5e1dfd6c
+SHA512:
+  metadata.gz: 5b17c0c0917b850ad1265cee471e88f94e52d510488387f5075226d1a27b2217d04874149bd72ed95b76dd61e41419b9bb52ca26ca65e8e10be4d086e5f879e8
+  data.tar.gz: 302755ff2c233d61f2238169a73766cfd285a14be5a0330de84a08c8b286394a523f030e3632f29fff3f311c3db80540d308944cb7ac820a7ecc83e109220675

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction: including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,130 @@
+# web_ruby_ui 💎🌐
+
+[![Gem Version](https://badge.fury.io/rb/web_ruby_ui.svg)](https://badge.fury.io/rb/web_ruby_ui)
+[![GEM Downloads](https://img.shields.io/gem/dt/web_ruby_ui.svg)](https://rubygems.org/gems/web_ruby_ui)
+[![CI Status](https://github.com/aditya-8108/web_ruby_ui/actions/workflows/ci.yml/badge.svg)](https://github.com/aditya-8108/web_ruby_ui/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**The 100% Pure Ruby Frontend Web Framework in WebAssembly.**
+
+Build interactive Single-Page Applications (SPAs) entirely in Ruby running inside the browser via `ruby.wasm` — **Zero JavaScript, Zero React, Zero Node, and Zero NPM dependencies.**
+
+---
+
+## Key Features 🚀
+
+- ⚡ **100% Pure Ruby Frontend**: Write interactive web components, event listeners, and state management in native Ruby.
+- 🔄 **Reactive State Management**: Define `state :count, default: 0`. Updating state (`self.count += 1`) automatically re-renders component views.
+- 🌳 **Virtual DOM Diffing**: In-memory `VNode` tree generation and diffing engine for optimal browser DOM rendering.
+- 🗺️ **Client-Side SPA Routing**: Single-page application route matching (`Router`) for multi-view Ruby web apps.
+- 🛠️ **Dev Server & CLI Tooling**: `web_ruby_ui dev` launches a local WebAssembly dev server with instant browser hot-loading.
+
+---
+
+## Architecture Overview 📐
+
+```
+┌─────────────────────────────────────────────────────────────┐
+  BROWSER (WebAssembly Environment)
+  ┌─────────────────────────────────────────────────────────┐
+    JS::Object (Browser DOM APIs)
+         ▲
+         │ DOM Events (onclick, oninput) & Render Patches
+         ▼
+    WebRubyUI::DOM (Event Bridge & JS Interop)
+         ▲
+         │ In-Memory VNode Tree & Patch Diffing
+         ▼
+    WebRubyUI::Component (Reactive State & HTML DSL)
+  └─────────────────────────────────────────────────────────┘
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'web_ruby_ui'
+```
+
+And then execute:
+```bash
+bundle install
+```
+
+---
+
+## Quickstart (Todo App in Pure Ruby)
+
+Create a reactive Single-Page Application without touching JavaScript:
+
+```ruby
+require 'web_ruby_ui'
+
+class TodoApp < WebRubyUI::Component
+  state :items, default: [
+    { id: 1, title: 'Learn Ruby WebAssembly', completed: true },
+    { id: 2, title: 'Build WebRubyUI frontend framework', completed: true }
+  ]
+  state :new_title, default: ''
+
+  def render
+    div(class: 'max-w-md mx-auto my-10 p-6 bg-white rounded-xl shadow-lg') do
+      h1(class: 'text-2xl font-bold text-indigo-600 mb-4') { 'RubyWasm Todo App 💎' }
+
+      # Add Todo Form
+      div(class: 'flex mb-4 gap-2') do
+        input(
+          type: 'text',
+          class: 'flex-1 px-4 py-2 border rounded-lg',
+          placeholder: 'What needs to be done?',
+          value: new_title,
+          oninput: ->(e) { self.new_title = e[:target][:value] }
+        )
+        button(
+          class: 'px-4 py-2 bg-indigo-600 text-white rounded-lg font-semibold',
+          onclick: -> { add_todo }
+        ) { 'Add' }
+      end
+
+      # Todo List
+      ul(class: 'divide-y divide-gray-200') do
+        items.each do |item|
+          li(class: 'py-3 flex items-center justify-between') do
+            span(class: item[:completed] ? 'line-through text-gray-400' : 'text-gray-800') do
+              item[:title]
+            end
+          end
+        end
+      end
+    end
+  end
+
+  private
+
+  def add_todo
+    return if new_title.nil? || new_title.strip.empty?
+    self.items = items + [{ id: Time.now.to_i, title: new_title.strip, completed: false }]
+    self.new_title = ''
+  end
+end
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+| --- | --- |
+| `web_ruby_ui new my_app` | Generates a new WebRubyUI project structure |
+| `web_ruby_ui dev` | Launches a local WebAssembly web server at `http://localhost:8000` |
+| `web_ruby_ui build` | Packages standalone `index.html` for production deployment |
+
+---
+
+## License
+
+MIT License.

data/bin/web_ruby_ui

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require_relative '../lib/web_ruby_ui'
+
+WebRubyUI::CLI.start(ARGV)

data/lib/web_ruby_ui/cli.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'webrick'
+require 'fileutils'
+
+module WebRubyUI
+  class CLI < Thor
+    map 'new' => :new_project
+
+    desc 'dev [APP_DIR]', 'Start a local WebAssembly dev server for a WebRubyUI app'
+    method_option :port, type: :numeric, default: 8000, aliases: '-p', desc: 'Port to run dev server on'
+    def dev(app_dir = '.')
+      port = options[:port]
+      say "🚀 Starting WebRubyUI Wasm dev server on http://localhost:#{port}...", :green
+
+      target_dir = File.expand_path(app_dir)
+      index_path = File.join(target_dir, 'index.html')
+
+      ensure_index_html(index_path)
+
+      server = WEBrick::HTTPServer.new(
+        Port: port,
+        DocumentRoot: target_dir,
+        AccessLog: [],
+        Logger: WEBrick::Log.new(File::NULL)
+      )
+
+      trap('INT') { server.shutdown }
+      server.start
+    end
+
+    desc 'build [APP_DIR]', 'Build standalone HTML/Wasm package for production deployment'
+    def build(app_dir = '.')
+      target_dir = File.expand_path(app_dir)
+      index_path = File.join(target_dir, 'index.html')
+
+      ensure_index_html(index_path)
+      say "✨ Successfully built WebRubyUI Wasm package in #{target_dir}/index.html", :green
+    end
+
+    desc 'new APP_NAME', 'Generate a new WebRubyUI Single-Page App project'
+    def new_project(app_name)
+      target_dir = File.expand_path(app_name)
+      FileUtils.mkdir_p(File.join(target_dir, 'app'))
+
+      app_rb = <<~RUBY
+        # frozen_string_literal: true
+
+        require 'web_ruby_ui'
+
+        class App < WebRubyUI::Component
+          state :count, default: 0
+
+          def render
+            div(class: 'card') do
+              h1 { "Welcome to WebRubyUI!" }
+              p { "Count: \#{count}" }
+              button(onclick: -> { self.count += 1 }) { "Increment" }
+            end
+          end
+        end
+      RUBY
+
+      File.write(File.join(target_dir, 'app', 'app.rb'), app_rb)
+      ensure_index_html(File.join(target_dir, 'index.html'))
+      say "🎉 Created new WebRubyUI project in #{target_dir}!", :green
+    end
+
+    private
+
+    def ensure_index_html(path)
+      return if File.exist?(path)
+
+      html = <<~HTML
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <meta charset="utf-8">
+          <title>WebRubyUI Application</title>
+          <script src="https://cdn.jsdelivr.net/npm/@ruby/3.3-wasm-wasi@2.5.0/dist/browser.script.iife.js"></script>
+        </head>
+        <body>
+          <div id="app">Loading WebRubyUI Wasm...</div>
+          <script type="ruby" src="./app/app.rb"></script>
+        </body>
+        </html>
+      HTML
+
+      File.write(path, html)
+    end
+  end
+end

data/lib/web_ruby_ui/component.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative 'vnode'
+require_relative 'dom'
+
+module WebRubyUI
+  # Base Component class providing reactive state tracking and HTML builder DSL.
+  class Component
+    class << self
+      def state(name, default: nil)
+        state_definitions[name] = default
+
+        define_method(name) do
+          @state_values[name]
+        end
+
+        define_method("#{name}=") do |new_val|
+          old_val = @state_values[name]
+          return unless old_val != new_val
+
+          @state_values[name] = new_val
+          re_render!
+        end
+      end
+
+      def state_definitions
+        @state_definitions ||= {}
+      end
+    end
+
+    attr_reader :mount_element_id
+
+    def initialize(props = {})
+      @props = props
+      @state_values = {}
+      self.class.state_definitions.each do |name, default|
+        @state_values[name] = default
+      end
+      @current_vnode = nil
+      @children_stack = []
+    end
+
+    def mount(element_id)
+      @mount_element_id = element_id
+      re_render!
+    end
+
+    def render
+      raise NotImplementedError, "#{self.class.name}#render must be implemented"
+    end
+
+    def re_render!
+      new_vnode = build_vnode_tree
+      @current_vnode = new_vnode
+
+      DOM.render_to_element(@mount_element_id, new_vnode) if @mount_element_id
+      new_vnode
+    end
+
+    # HTML Builder DSL methods
+    %i[div h1 h2 h3 p span button input ul li a section header footer form label].each do |tag_name|
+      define_method(tag_name) do |attrs = {}, &block|
+        element(tag_name, attrs, &block)
+      end
+    end
+
+    private
+
+    def build_vnode_tree
+      @children_stack = []
+      vnode = render
+      vnode.is_a?(VNode) ? vnode : VNode.new(tag: :div, text_content: vnode.to_s)
+    end
+
+    def element(tag, attrs = {}, &block)
+      children = []
+      text_content = nil
+
+      if block
+        current_children = []
+        @children_stack.push(current_children)
+
+        result = instance_eval(&block)
+        text_content = result.to_s if current_children.empty? && result && !result.is_a?(VNode)
+
+        children = @children_stack.pop
+      end
+
+      node = VNode.new(tag: tag, attributes: attrs, children: children, text_content: text_content)
+      @children_stack.last << node if @children_stack.any?
+      node
+    end
+  end
+end

data/lib/web_ruby_ui/dom.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module WebRubyUI
+  # Bridge to browser DOM via WebAssembly JS interop (JS::Object) or in-memory simulation.
+  class DOM
+    class << self
+      def event_registry
+        @event_registry ||= {}
+      end
+
+      def register_event(element_id, event_type, handler)
+        key = "#{element_id}_#{event_type}"
+        event_registry[key] = handler
+      end
+
+      def trigger_event(element_id, event_type, event_data = {})
+        key = "#{element_id}_#{event_type}"
+        handler = event_registry[key]
+        handler&.call(event_data)
+      end
+
+      def render_to_element(element_id, vnode)
+        if Object.const_defined?(:JS)
+          js_document = JS.global[:document]
+          js_target = js_document.getElementById(element_id.to_s)
+          if js_target
+            js_target[:innerHTML] = render_html_string(vnode)
+            bind_js_events(js_document, vnode)
+          end
+        end
+
+        render_html_string(vnode)
+      end
+
+      def render_html_string(vnode)
+        return CGI.escapeHTML(vnode.text_content.to_s) unless vnode.is_a?(VNode)
+
+        attrs = vnode.attributes.map do |k, v|
+          next if k.to_s.start_with?('on') # Skip event handlers in HTML attributes
+
+          "#{k}=\"#{v}\""
+        end.compact.join(' ')
+
+        attr_str = attrs.empty? ? '' : " #{attrs}"
+
+        if vnode.children.empty? && vnode.text_content
+          escaped_text = CGI.escapeHTML(vnode.text_content.to_s)
+          "<#{vnode.tag}#{attr_str}>#{escaped_text}</#{vnode.tag}>"
+        else
+          children_html = vnode.children.map { |c| render_html_string(c) }.join
+          "<#{vnode.tag}#{attr_str}>#{children_html}</#{vnode.tag}>"
+        end
+      end
+
+      private
+
+      def bind_js_events(document, vnode)
+        return unless vnode.is_a?(VNode)
+
+        vnode.attributes.each do |attr_name, handler|
+          next unless attr_name.to_s.start_with?('on') && handler.is_a?(Proc)
+
+          event_type = attr_name.to_s.sub(/\Aon/, '')
+          elem_id = vnode.attributes[:id] || "wrui_#{vnode.object_id}"
+          register_event(elem_id, event_type, handler)
+
+          js_elem = document.getElementById(elem_id.to_s)
+          next unless js_elem
+
+          js_elem.addEventListener(event_type) do |e|
+            handler.call(e)
+          end
+        end
+
+        vnode.children.each { |c| bind_js_events(document, c) }
+      end
+    end
+  end
+end

data/lib/web_ruby_ui/router.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module WebRubyUI
+  # Client-side router matching URL paths to WebRubyUI Components.
+  class Router
+    attr_reader :routes
+
+    def initialize
+      @routes = {}
+    end
+
+    def route(path, component_class)
+      @routes[path.to_s] = component_class
+    end
+
+    def match(path)
+      clean_path = path.to_s.empty? ? '/' : path.to_s
+      @routes[clean_path] || @routes['/']
+    end
+
+    def navigate(path, target_element_id = 'app')
+      component_class = match(path)
+      return nil unless component_class
+
+      component = component_class.new(path: path)
+      component.mount(target_element_id)
+      component
+    end
+  end
+end

data/lib/web_ruby_ui/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WebRubyUI
+  VERSION = '0.1.0'
+end

data/lib/web_ruby_ui/vnode.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module WebRubyUI
+  # Represents a virtual DOM node in pure Ruby memory.
+  class VNode
+    attr_reader :tag, :attributes, :children, :text_content
+
+    def initialize(tag:, attributes: {}, children: [], text_content: nil)
+      @tag = tag.to_s.downcase
+      @attributes = attributes || {}
+      @children = children || []
+      @text_content = text_content
+    end
+
+    def to_h
+      {
+        tag: @tag,
+        attributes: @attributes,
+        children: @children.map { |c| c.is_a?(VNode) ? c.to_h : c },
+        text_content: @text_content
+      }
+    end
+
+    def diff(other_vnode)
+      patches = []
+
+      return [{ type: :remove }] if other_vnode.nil?
+
+      return [{ type: :replace, new_node: other_vnode }] if tag != other_vnode.tag
+
+      patches << { type: :update_text, new_text: other_vnode.text_content } if text_content != other_vnode.text_content
+
+      # Attr diffing
+      attr_diff = diff_attributes(attributes, other_vnode.attributes)
+      patches << { type: :update_attrs, attrs: attr_diff } if attr_diff.any?
+
+      patches
+    end
+
+    private
+
+    def diff_attributes(old_attrs, new_attrs)
+      diffs = {}
+      (old_attrs.keys | new_attrs.keys).each do |k|
+        diffs[k] = new_attrs[k] if old_attrs[k] != new_attrs[k]
+      end
+      diffs
+    end
+  end
+end

data/lib/web_ruby_ui.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'web_ruby_ui/version'
+require_relative 'web_ruby_ui/vnode'
+require_relative 'web_ruby_ui/dom'
+require_relative 'web_ruby_ui/component'
+require_relative 'web_ruby_ui/router'
+require_relative 'web_ruby_ui/cli'
+
+module WebRubyUI
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: web_ruby_ui
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aditya
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: Build reactive, single-page web applications with components, state management,
+  and virtual DOM diffing in pure Ruby running on WebAssembly.
+email: 
+executables:
+- web_ruby_ui
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/web_ruby_ui
+- lib/web_ruby_ui.rb
+- lib/web_ruby_ui/cli.rb
+- lib/web_ruby_ui/component.rb
+- lib/web_ruby_ui/dom.rb
+- lib/web_ruby_ui/router.rb
+- lib/web_ruby_ui/version.rb
+- lib/web_ruby_ui/vnode.rb
+homepage: https://github.com/aditya-8108/web_ruby_ui
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aditya-8108/web_ruby_ui
+  source_code_uri: https://github.com/aditya-8108/web_ruby_ui
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: 100% Pure Ruby Frontend Web Framework in WebAssembly
+test_files: []