ruwi 0.10.0

data/docs/conditional-rendering.md

@@ -0,0 +1,119 @@
+# Conditional Rendering with r-if
+
+ruwi provides the `r-if` directive for conditional rendering of elements based on state or computed values:
+
+```ruby
+# Component demonstrating r-if conditional rendering
+ConditionalComponent = Ruwi.define_component(
+  state: ->() {
+    {
+      show_message: false,
+      counter: 0
+    }
+  },
+
+  template: ->() {
+    Ruwi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <div>
+        <!-- Simple boolean condition -->
+        <div r-if="{state[:show_message]}">
+          <p>This message is conditionally rendered!</p>
+        </div>
+
+        <!-- Using r-if, r-elsif, r-else for multiple conditions -->
+        <div r-if="{state[:counter] > 0}">
+          <p>Counter is positive: {state[:counter]}</p>
+        </div>
+
+        <div r-elsif="{state[:counter] < 0}">
+          <p>Counter is negative: {state[:counter]}</p>
+        </div>
+
+        <div r-else>
+          <p>Counter is zero</p>
+        </div>
+
+        <!-- Toggle button -->
+        <button on="{click: ->() { toggle_message }}">
+          {state[:show_message] ? "Hide" : "Show"} Message
+        </button>
+      </div>
+    HTML
+  },
+
+  methods: {
+    toggle_message: ->() {
+      update_state(show_message: !state[:show_message])
+    }
+  }
+)
+```
+
+## r-if, r-elsif, r-else Syntax
+
+The conditional directives work together to create if-elsif-else chains:
+
+### Basic Usage
+
+- **`r-if="{condition}"`**: Renders the element when condition is truthy
+- **`r-elsif="{condition}"`**: Renders when previous conditions are falsy and this condition is truthy
+- **`r-else`**: Renders when all previous conditions are falsy (no condition needed)
+
+### Expression Evaluation
+
+All conditional expressions are evaluated as Ruby code within curly braces `{}`:
+
+- Use any valid Ruby expression that returns a truthy or falsy value
+- Access component state with `state[:key]`
+- Access props with `props[:key]`
+- Support for comparison operators (`>`, `<`, `==`, `!=`, etc.)
+- Support for logical operators (`&&`, `||`, `!`)
+- Support for method calls and complex expressions
+
+### Conditional Chain Rules
+
+1. **Sequential Processing**: Conditions are evaluated in order (r-if → r-elsif → r-else)
+2. **Mutual Exclusivity**: Only one element in a conditional chain will render
+3. **Grouping**: Consecutive conditional elements form a single conditional group
+4. **Breaking**: A new `r-if` breaks the current conditional chain and starts a new one
+
+### Advanced Example
+
+```ruby
+# Real-world example with loading states and data
+LoadingComponent = Ruwi.define_component(
+  state: ->() {
+    {
+      is_loading: false,
+      data: nil,
+      error: nil
+    }
+  },
+
+  template: ->() {
+    Ruwi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <div>
+        <!-- Loading state -->
+        <p r-if="{state[:is_loading]}">Loading...</p>
+
+        <!-- Error state -->
+        <div r-elsif="{state[:error]}" style="color: red;">
+          <p>Error: {state[:error]}</p>
+          <button on="{click: ->() { retry_load }}">Retry</button>
+        </div>
+
+        <!-- Success state with data -->
+        <div r-elsif="{state[:data]}">
+          <h2>{state[:data][:title]}</h2>
+          <p>{state[:data][:description]}</p>
+        </div>
+
+        <!-- Initial state (no loading, no error, no data) -->
+        <button r-else on="{click: ->() { load_data }}">
+          Load Data
+        </button>
+      </div>
+    HTML
+  }
+)
+```

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 = Ruwi.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
+
+    Ruwi::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 ruwi 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
+
+ruwi 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 = Ruwi.define_component(
+  template: ->() {
+    Ruwi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <li>{props[:todo]}</li>
+    HTML
+  }
+)
+
+# Main list component demonstrating r-for usage
+List = Ruwi.define_component(
+  template: ->() {
+    Ruwi::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 = Ruwi::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/.gitignore

@@ -0,0 +1,4 @@
+ruby.wasm
+/rubies
+/build
+/dist

data/examples/Gemfile

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

data/examples/Gemfile.lock

@@ -0,0 +1,39 @@
+PATH
+  remote: ../..
+  specs:
+    ruwi (0.9.1)
+      js (~> 2.7)
+      listen (~> 3.8)
+      puma (~> 6.0)
+      rack (~> 3.0)
+      ruby_wasm (~> 2.7)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ffi (1.17.2-arm64-darwin)
+    js (2.7.2)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    nio4r (2.7.5)
+    puma (6.6.1)
+      nio4r (~> 2.0)
+    rack (3.2.4)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    ruby_wasm (2.7.2)
+      logger
+    ruby_wasm (2.7.2-arm64-darwin)
+      logger
+
+PLATFORMS
+  arm64-darwin
+
+DEPENDENCIES
+  ruwi!
+
+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/ruwi.js"
+        : "https://unpkg.com/ruwi@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 = Ruwi.define_component(
+  # Initialize component state
+  state: ->(props) {
+    { count: props[:count] || 0 }
+  },
+
+  # Render the counter component
+  template: ->() {
+    Ruwi::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 = Ruwi.define_component(
+  template: ->() {
+    Ruwi::Template::Parser.parse_and_eval(<<~HTML, binding)
+      <button on="{ click: ->() { emit('click_button') } }">
+        {props[:label]}
+      </button>
+    HTML
+  }
+)
+
+# app_a to be destroyed
+app_a = Ruwi::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 = Ruwi::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/ruwi.js"
+        : "https://unpkg.com/ruwi@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 = Ruwi::Vdom.h("div", {}, [Ruwi::Vdom.h("h1", {}, ["Hello, world!"])])
+h1_a_element = JS.global[:document].getElementById("h1-a")
+Ruwi::Dom::Events.add_event_listener("click", ->(e) { puts "clicked" }, h1_a_element)
+Ruwi::Dom::Attributes.set_attributes(h1_a_element, {
+  class: "bg-red-500"
+})
+Ruwi::Dom::Attributes.set_attribute(h1_a_element, "data-test", "test")
+Ruwi::Dom::Attributes.set_class(h1_a_element, "bg-blue-500")
+Ruwi::Dom::Attributes.set_style(h1_a_element, "background-color", "red")
+Ruwi::Dom::Attributes.remove_attribute(h1_a_element, "data-test")
+Ruwi::Dom::Attributes.remove_style(h1_a_element, "background-color")
+
+Ruwi::Dom::MountDom.execute(h_a, h1_a_element)
+Ruwi::Dom::DestroyDom.execute(h_a)
+
+# h_b to be mounted
+h_b = Ruwi::Vdom.h("div", {}, [Ruwi::Vdom.h("h1", {}, ["Hello, world!"])])
+h1_b_element = JS.global[:document].getElementById("h1-b")
+Ruwi::Dom::Events.add_event_listener("click", ->(e) { puts "clicked" }, h1_b_element)
+Ruwi::Dom::Attributes.set_attributes(h1_b_element, {
+  class: "bg-red-500"
+})
+Ruwi::Dom::Attributes.set_attribute(h1_b_element, "data-test", "test")
+Ruwi::Dom::Attributes.set_class(h1_b_element, "bg-red-500")
+Ruwi::Dom::Attributes.set_style(h1_b_element, "background-color", "blue")
+Ruwi::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/ruwi.js"
+        : "https://unpkg.com/ruwi@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 = Ruwi.define_component(
+  # Initialize component state
+  state: ->() {
+    {
+      url_name: '',
+      is_valid: false
+    }
+  },
+
+  # Render the input component
+  template: ->() {
+    Ruwi::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 = Ruwi::App.create(InputForm)
+app_element = JS.global[:document].getElementById("app")
+app.mount(app_element)