ruby_wasm_ui 0.8.1

data/docs/lifecycle-hooks.md

@@ -0,0 +1,75 @@
+# Lifecycle Hooks
+
+Components support lifecycle hooks to execute code at specific points in a component's lifecycle:
+
+```ruby
+RandomCocktailComponent = RubyWasmUi.define_component(
+  state: ->() {
+    {
+      is_loading: false,
+      cocktail: nil
+    }
+  },
+
+  methods: {
+    fetch_cocktail: -> {
+      # Set loading state
+      update_state(is_loading: true, cocktail: nil)
+
+      # Use Fiber for asynchronous API call
+      Fiber.new do
+        response = JS.global.fetch("https://www.thecocktaildb.com/api/json/v1/1/random.php").await
+        response.call(:json).then(->(data) {
+          update_state(is_loading: false, cocktail: data[:drinks][0])
+        }).catch(->(error) {
+          update_state(is_loading: false, cocktail: nil)
+        })
+      end.transfer
+    }
+  },
+
+  # Called after the component is mounted to the DOM
+  on_mounted: ->() {
+    fetch_cocktail
+  },
+
+  template: ->() {
+    is_loading = state[:is_loading] # Used in template
+    cocktail = state[:cocktail] # Used in template
+
+    template = <<~HTML
+      <div>
+        <p r-if="{is_loading}">Loading...</p>
+        <button r-elsif="{cocktail.nil?}" on="{click: ->() { fetch_cocktail }}">
+          Get a cocktail
+        </button>
+        <template r-else>
+          <h2>{cocktail['strDrink']}</h2>
+          <p>{cocktail['strInstructions']}</p>
+          <img src="{cocktail['strDrinkThumb']}" alt="{cocktail['strDrink']}" style="width: 300px; height: 300px" />
+          <button on="{click: ->() { fetch_cocktail }}">
+            Get another cocktail
+          </button>
+        </template>
+      </div>
+    HTML
+
+    RubyWasmUi::Template::Parser.parse_and_eval(template, binding)
+  }
+)
+```
+
+## Available Lifecycle Hooks
+
+### on_mounted
+
+The `on_mounted` hook is called after the component is mounted to the DOM. This is useful for:
+
+- Making initial API calls
+- Setting up event listeners
+- Initializing third-party libraries
+- Performing DOM manipulations that require the element to be in the document
+
+## Asynchronous Operations
+
+Note: Unlike JavaScript frameworks, asynchronous operations in ruby-wasm-ui are designed to use Ruby's Fiber system rather than Promises.

data/docs/list-rendering.md

@@ -0,0 +1,51 @@
+# List Rendering with r-for
+
+ruby-wasm-ui provides the `r-for` directive for rendering lists of items. You can use `r-for` with both components and regular HTML elements:
+
+```ruby
+# Define a reusable list item component
+ListItem = RubyWasmUi.define_component(
+  template: ->() {
+    RubyWasmUi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <li>{props[:todo]}</li>
+    HTML
+  }
+)
+
+# Main list component demonstrating r-for usage
+List = RubyWasmUi.define_component(
+  template: ->() {
+    RubyWasmUi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <ul>
+        <!-- Using r-for with a component -->
+        <ListItem
+          r-for="{todo in props[:todos]}"
+          todo="{todo}"
+        />
+
+        <!-- Using r-for with regular HTML elements -->
+        <li r-for="todo in props[:todos]">
+          { todo }
+        </li>
+      </ul>
+    HTML
+  }
+)
+
+# Create and mount the app with initial data
+app = RubyWasmUi::App.create(List, { todos: ['foo', 'bar', 'baz'] })
+app_element = JS.global[:document].getElementById("app")
+app.mount(app_element)
+```
+
+## r-for Syntax
+
+The `r-for` directive uses the syntax `"item in collection"` where:
+
+- `item` is the variable name for each iteration
+- `collection` is the array or enumerable to iterate over
+
+You can use `r-for` in two ways:
+
+1. **With components**: Pass the current item as props to child components
+2. **With HTML elements**: Directly render HTML elements for each item

data/examples/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "ruby_wasm_ui", path: "../../"

data/examples/Gemfile.lock

@@ -0,0 +1,41 @@
+PATH
+  remote: ../..
+  specs:
+    ruby_wasm_ui (0.8.1)
+      js (~> 2.7)
+      ruby_wasm (~> 2.7)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    js (2.7.2)
+    logger (1.7.0)
+    ruby_wasm (2.7.2)
+      logger
+    ruby_wasm (2.7.2-aarch64-linux)
+      logger
+    ruby_wasm (2.7.2-aarch64-linux-musl)
+      logger
+    ruby_wasm (2.7.2-arm64-darwin)
+      logger
+    ruby_wasm (2.7.2-x86_64-darwin)
+      logger
+    ruby_wasm (2.7.2-x86_64-linux)
+      logger
+    ruby_wasm (2.7.2-x86_64-linux-musl)
+      logger
+
+PLATFORMS
+  aarch64-linux
+  aarch64-linux-musl
+  arm64-darwin
+  ruby
+  x86_64-darwin
+  x86_64-linux
+  x86_64-linux-musl
+
+DEPENDENCIES
+  ruby_wasm_ui!
+
+BUNDLED WITH
+   2.7.2

data/examples/Makefile

@@ -0,0 +1,15 @@
+.PHONY: setup
+setup: ## Setup app
+	bundle install
+
+.PHONY: build
+build: ## Build app
+	bundle exec rbwasm build --ruby-version 3.4 -o ruby.wasm
+
+.PHONY: pack
+pack: ## Pack app
+	bundle exec rbwasm pack ruby.wasm --dir ./src::./src -o src.wasm
+
+.PHONY: serve
+serve: ## Serve app
+	npx http-server . -o './src' --cors -P 'http://localhost:8080?' -c-1

data/examples/npm-packages/runtime/counter/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+    <script>
+      const urlParams = new URLSearchParams(window.location.search);
+      const isDev = urlParams.get("env") === "DEV";
+      const script = document.createElement("script");
+      script.defer = true;
+      script.src = isDev
+        ? "../../../../packages/npm-packages/runtime/dist/ruby-wasm-ui.js"
+        : "https://unpkg.com/ruby-wasm-ui@latest";
+      document.head.appendChild(script);
+    </script>
+    <script defer type="text/ruby" src="index.rb"></script>
+
+    <title>Counter</title>
+  </head>
+
+  <body>
+    <h1>Counter</h1>
+    <div id="app-a"></div>
+    <div id="app-b"></div>
+  </body>
+</html>

data/examples/npm-packages/runtime/counter/index.rb

@@ -0,0 +1,62 @@
+require "js"
+
+# Counter component using the latest component-based API with TemplateParser
+CounterComponent = RubyWasmUi.define_component(
+  # Initialize component state
+  state: ->(props) {
+    { count: props[:count] || 0 }
+  },
+
+  # Render the counter component
+  template: ->() {
+    RubyWasmUi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <div>
+        <div>{state[:count]}</div>
+        <!-- Both ButtonComponent and button-component are valid -->
+        <ButtonComponent
+          label="Increment"
+          on="{ click_button: -> { increment } }">
+        </ButtonComponent>
+        <button-component
+          label="Decrement"
+          on="{ click_button: -> { decrement } }"
+        />
+      </div>
+    HTML
+},
+
+  # Component methods
+  methods: {
+    # Increment the counter
+    increment: ->() {
+      update_state(count: state[:count] + 1)
+    },
+
+    # Decrement the counter
+    decrement: ->() {
+      update_state(count: state[:count] - 1)
+    }
+  }
+)
+
+# Button component - reusable button with click handler
+ButtonComponent = RubyWasmUi.define_component(
+  template: ->() {
+    RubyWasmUi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <button on="{ click: ->() { emit('click_button') } }">
+        {props[:label]}
+      </button>
+    HTML
+  }
+)
+
+# app_a to be destroyed
+app_a = RubyWasmUi::App.create(CounterComponent, count: 0)
+app_element_a = JS.global[:document].getElementById("app-a")
+app_a.mount(app_element_a)
+app_a.unmount
+
+# app_b to be mounted
+app_b = RubyWasmUi::App.create(CounterComponent, count: 10)
+app_element_b = JS.global[:document].getElementById("app-b")
+app_b.mount(app_element_b)

data/examples/npm-packages/runtime/counter/index.spec.js

@@ -0,0 +1,42 @@
+import { test, expect } from "@playwright/test";
+
+test.describe("Counter Example", () => {
+  test("should display counter and handle increment/decrement operations", async ({
+    page,
+  }) => {
+    await page.goto("/examples/npm-packages/runtime/counter/index.html?env=DEV");
+    await page.waitForTimeout(3000);
+
+    // Check the page title
+    await expect(page).toHaveTitle("Counter");
+
+    // Check the main heading
+    await expect(page.locator("h1")).toHaveText("Counter");
+
+    // Check that app-b is mounted with initial count of 10
+    const counterDisplay = page.locator("#app-b > div > div:first-child");
+    await expect(counterDisplay).toHaveText("10");
+
+    // Verify increment and decrement buttons are present
+    const incrementBtn = page.locator("#app-b button").first();
+    const decrementBtn = page.locator("#app-b button").last();
+    await expect(incrementBtn).toHaveText("Increment");
+    await expect(decrementBtn).toHaveText("Decrement");
+
+    // Test increment operations
+    await incrementBtn.click();
+    await incrementBtn.click();
+    await incrementBtn.click();
+    await page.waitForTimeout(100);
+    await expect(counterDisplay).toHaveText("13");
+
+    // Test decrement operations
+    await decrementBtn.click();
+    await decrementBtn.click();
+    await decrementBtn.click();
+    await decrementBtn.click();
+    await decrementBtn.click();
+    await page.waitForTimeout(100);
+    await expect(counterDisplay).toHaveText("8");
+  });
+});

data/examples/npm-packages/runtime/hello/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+    <script>
+      const urlParams = new URLSearchParams(window.location.search);
+      const isDev = urlParams.get("env") === "DEV";
+      const script = document.createElement("script");
+      script.defer = true;
+      script.src = isDev
+        ? "../../../../packages/npm-packages/runtime/dist/ruby-wasm-ui.js"
+        : "https://unpkg.com/ruby-wasm-ui@latest";
+      document.head.appendChild(script);
+    </script>
+    <script defer type="text/ruby" src="index.rb"></script>
+
+    <title>Hello World</title>
+  </head>
+
+  <body>
+    <h1>Hello World</h1>
+    <div id="h1-a"></div>
+    <div id="h1-b"></div>
+  </body>
+</html>

data/examples/npm-packages/runtime/hello/index.rb

@@ -0,0 +1,29 @@
+require "js"
+
+# h_a to be destroyed
+h_a = RubyWasmUi::Vdom.h("div", {}, [RubyWasmUi::Vdom.h("h1", {}, ["Hello, world!"])])
+h1_a_element = JS.global[:document].getElementById("h1-a")
+RubyWasmUi::Dom::Events.add_event_listener("click", ->(e) { puts "clicked" }, h1_a_element)
+RubyWasmUi::Dom::Attributes.set_attributes(h1_a_element, {
+  class: "bg-red-500"
+})
+RubyWasmUi::Dom::Attributes.set_attribute(h1_a_element, "data-test", "test")
+RubyWasmUi::Dom::Attributes.set_class(h1_a_element, "bg-blue-500")
+RubyWasmUi::Dom::Attributes.set_style(h1_a_element, "background-color", "red")
+RubyWasmUi::Dom::Attributes.remove_attribute(h1_a_element, "data-test")
+RubyWasmUi::Dom::Attributes.remove_style(h1_a_element, "background-color")
+
+RubyWasmUi::Dom::MountDom.execute(h_a, h1_a_element)
+RubyWasmUi::Dom::DestroyDom.execute(h_a)
+
+# h_b to be mounted
+h_b = RubyWasmUi::Vdom.h("div", {}, [RubyWasmUi::Vdom.h("h1", {}, ["Hello, world!"])])
+h1_b_element = JS.global[:document].getElementById("h1-b")
+RubyWasmUi::Dom::Events.add_event_listener("click", ->(e) { puts "clicked" }, h1_b_element)
+RubyWasmUi::Dom::Attributes.set_attributes(h1_b_element, {
+  class: "bg-red-500"
+})
+RubyWasmUi::Dom::Attributes.set_attribute(h1_b_element, "data-test", "test")
+RubyWasmUi::Dom::Attributes.set_class(h1_b_element, "bg-red-500")
+RubyWasmUi::Dom::Attributes.set_style(h1_b_element, "background-color", "blue")
+RubyWasmUi::Dom::MountDom.execute(h_b, h1_b_element)

data/examples/npm-packages/runtime/hello/index.spec.js

@@ -0,0 +1,53 @@
+import { test, expect } from "@playwright/test";
+
+test.describe("Hello Example", () => {
+  test("should display hello world content and handle click events", async ({
+    page,
+  }) => {
+    // Navigate to the hello example
+    await page.goto("/examples/npm-packages/runtime/hello/index.html?env=DEV");
+
+    // Wait for Ruby WASM to load and initialize
+    await page.waitForTimeout(3000);
+
+    // Check the page title
+    await expect(page).toHaveTitle("Hello World");
+
+    // Check the main heading (first h1 in body)
+    await expect(page.locator("body > h1")).toHaveText("Hello World");
+
+    // Check that the h1-b div contains the "Hello, world!" text
+    await expect(page.locator("#h1-b h1")).toHaveText("Hello, world!");
+
+    // Verify that h1-b element has the expected classes and styles
+    const h1BElement = page.locator("#h1-b");
+    await expect(h1BElement).toHaveClass(/bg-red-500/);
+    await expect(h1BElement).toHaveAttribute("data-test", "test");
+
+    // Check the inline style for background color
+    const computedStyle = await h1BElement.evaluate(
+      (el) => getComputedStyle(el).backgroundColor
+    );
+    expect(computedStyle).toBe("rgb(0, 0, 255)"); // blue color
+
+    // Test click event handling
+    const consoleMessages = [];
+    page.on("console", (msg) => {
+      if (msg.type() === "log") {
+        consoleMessages.push(msg.text());
+      }
+    });
+
+    // Click on the h1-b element
+    await h1BElement.click();
+
+    // Wait a bit for the console log to appear
+    await page.waitForTimeout(500);
+
+    // Verify that the click event was logged (may have newline)
+    const hasClickedMessage = consoleMessages.some((msg) =>
+      msg.includes("clicked")
+    );
+    expect(hasClickedMessage).toBe(true);
+  });
+});

data/examples/npm-packages/runtime/input/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+    <script>
+      const urlParams = new URLSearchParams(window.location.search);
+      const isDev = urlParams.get("env") === "DEV";
+      const script = document.createElement("script");
+      script.defer = true;
+      script.src = isDev
+        ? "../../../../packages/npm-packages/runtime/dist/ruby-wasm-ui.js"
+        : "https://unpkg.com/ruby-wasm-ui@latest";
+      document.head.appendChild(script);
+    </script>
+    <script defer type="text/ruby" src="index.rb"></script>
+    <script defer src="https://cdn.tailwindcss.com"></script>
+
+    <title>Input</title>
+  </head>
+
+  <body>
+    <h1>Input</h1>
+    <div id="app"></div>
+  </body>
+</html>

data/examples/npm-packages/runtime/input/index.rb

@@ -0,0 +1,46 @@
+require "js"
+
+# input-form component using the latest component-based API
+InputForm = RubyWasmUi.define_component(
+  # Initialize component state
+  state: ->() {
+    {
+      url_name: '',
+      is_valid: false
+    }
+  },
+
+  # Render the input component
+  template: ->() {
+    RubyWasmUi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <form class="w-full max-w-sm">
+        <label class="block mb-2 text-sm font-medium text-700">User Name</label>
+        <input
+          type="text"
+          value="{state[:url_name]}"
+          class="{state[:is_valid] ? 'bg-green-50 border border-green-500 text-green-900 placeholder-green-700 text-sm rounded-lg focus:ring-green-500 focus:border-green-500 block w-full p-2.5 dark:bg-green-100 dark:border-green-400' : 'bg-red-50 border border-red-500 text-red-900 placeholder-red-700 text-sm rounded-lg focus:ring-red-500 focus:border-red-500 block w-full p-2.5 dark:bg-red-100 dark:border-red-400'}"
+          on="{input: ->(e) { update_url_name(e[:target][:value].to_s) }}" />
+        <p class="{state[:is_valid] ? 'mt-2 text-sm text-green-600 dark:text-green-500' : 'mt-2 text-sm text-red-600 dark:text-red-500'}">
+          {state[:is_valid] ? "Valid" : "User name must be at least 4 characters"}
+        </p>
+        <p>*User name must be at least 4 characters</p>
+      </form>
+    HTML
+  },
+
+  # Component methods
+  methods: {
+    # Update the URL name and validation status
+    # @param value [String] The new URL name value
+    update_url_name: ->(value) {
+      update_state(
+        url_name: value,
+        is_valid: value.length >= 4
+      )
+    }
+  }
+)
+
+app = RubyWasmUi::App.create(InputForm)
+app_element = JS.global[:document].getElementById("app")
+app.mount(app_element)

data/examples/npm-packages/runtime/input/index.spec.js

@@ -0,0 +1,58 @@
+import { test, expect } from "@playwright/test";
+
+test.describe("Input Example", () => {
+  test("should display input form and validate input length", async ({
+    page,
+  }) => {
+    await page.goto("/examples/npm-packages/runtime/input/index.html?env=DEV");
+    await page.waitForTimeout(3000);
+
+    // Check the page title
+    await expect(page).toHaveTitle("Input");
+
+    // Check form elements are present
+    await expect(page.locator("label")).toHaveText("User Name");
+    const input = page.locator('input[type="text"]');
+    await expect(input).toBeVisible();
+
+    // Check help text
+    await expect(page.locator("p").last()).toHaveText(
+      "*User name must be at least 4 characters"
+    );
+
+    // Check initial validation message (invalid state)
+    const validationMessage = page.locator("p").first();
+    await expect(validationMessage).toHaveText(
+      "User name must be at least 4 characters"
+    );
+    await expect(validationMessage).toHaveClass(/text-red-600/);
+    await expect(input).toHaveClass(/border-red-500/);
+
+    // Type less than 4 characters - should still be invalid
+    await input.fill("abc");
+    await page.waitForTimeout(100);
+    await expect(validationMessage).toHaveText(
+      "User name must be at least 4 characters"
+    );
+    await expect(validationMessage).toHaveClass(/text-red-600/);
+    await expect(input).toHaveClass(/border-red-500/);
+
+    // Type 4 or more characters - should become valid
+    await input.fill("abcd");
+    await page.waitForTimeout(100);
+    await expect(validationMessage).toHaveText("Valid");
+    await expect(validationMessage).toHaveClass(/text-green-600/);
+    await expect(input).toHaveClass(/border-green-500/);
+
+    // Clear input to make it invalid again
+    await input.fill("ab");
+    await page.waitForTimeout(100);
+
+    // Should be invalid again
+    await expect(input).toHaveValue("ab");
+    await expect(validationMessage).toHaveText(
+      "User name must be at least 4 characters"
+    );
+    await expect(validationMessage).toHaveClass(/text-red-600/);
+  });
+});

data/examples/npm-packages/runtime/list/index.html

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+    <script>
+      const urlParams = new URLSearchParams(window.location.search);
+      const isDev = urlParams.get("env") === "DEV";
+      const script = document.createElement("script");
+      script.defer = true;
+      script.src = isDev
+        ? "../../../../packages/npm-packages/runtime/dist/ruby-wasm-ui.js"
+        : "https://unpkg.com/ruby-wasm-ui@latest";
+      document.head.appendChild(script);
+    </script>
+    <script defer type="text/ruby" src="index.rb"></script>
+
+    <title>List</title>
+  </head>
+
+  <body>
+    <h1>List</h1>
+    <div id="app"></div>
+  </body>
+</html>

data/examples/npm-packages/runtime/list/index.rb

@@ -0,0 +1,33 @@
+require "js"
+
+ListItem = RubyWasmUi.define_component(
+  template: ->() {
+    RubyWasmUi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <li>{props[:todo]}</li>
+    HTML
+  }
+)
+
+List = RubyWasmUi.define_component(
+  template: ->() {
+
+    RubyWasmUi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <ul>
+        <!-- component -->
+        <ListItem
+          r-for="{todo in props[:todos]}"
+          todo="{todo}"
+        />
+        <!-- element -->
+        <li r-for="todo in props[:todos]">
+          { todo }
+        </li>
+      </ul>
+    HTML
+  }
+)
+
+# Create and mount the app
+app = RubyWasmUi::App.create(List, { todos: ['foo', 'bar', 'baz'] })
+app_element = JS.global[:document].getElementById("app")
+app.mount(app_element)