glimmer-dsl-web 0.0.8 → 0.0.10

data/README.md

@@ -1,11 +1,9 @@
-# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for Web 0.0.8 (Early Alpha)
+# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for Web 0.0.10 (Early Alpha)
 ## Ruby in the Browser Web GUI Frontend Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-web.svg)](http://badge.fury.io/rb/glimmer-dsl-web)
 [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for Web enables building Web GUI frontends using [Ruby in the Browser](https://www.youtube.com/watch?v=4AdcfbI6A4c), as per [Matz's recommendation in his RubyConf 2022 keynote speech to replace JavaScript with Ruby](https://youtu.be/knutsgHTrfQ?t=789). It aims at providing the simplest, most intuitive, most straight-forward, and most productive frontend library in existence. The library follows the Ruby way (with [DSLs](https://martinfowler.com/books/dsl.html) and [TIMTOWTDI](https://en.wiktionary.org/wiki/TMTOWTDI#English)) and the Rails way ([Convention over Configuration](https://rubyonrails.org/doctrine)) while supporting both Unidirectional (One-Way) Data-Binding (using `<=`) and Bidirectional (Two-Way) Data-Binding (using `<=>`). Dynamic rendering (and re-rendering) of HTML content is also supported via Content Data-Binding. You can finally live in pure Rubyland on the Web in both the frontend and backend with [Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web)!
-
-(the project plans to add component support very soon, albeit components are already supported by creating your own Ruby classes and having them render part of the GUI hierarchy)
+[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for Web enables building Web GUI frontends using [Ruby in the Browser](https://www.youtube.com/watch?v=4AdcfbI6A4c), as per [Matz's recommendation in his RubyConf 2022 keynote speech to replace JavaScript with Ruby](https://youtu.be/knutsgHTrfQ?t=789). It aims at providing the simplest, most intuitive, most straight-forward, and most productive frontend library in existence. The library follows the Ruby way (with [DSLs](https://martinfowler.com/books/dsl.html) and [TIMTOWTDI](https://en.wiktionary.org/wiki/TMTOWTDI#English)) and the Rails way ([Convention over Configuration](https://rubyonrails.org/doctrine)) while supporting both Unidirectional (One-Way) [Data-Binding](#hello-data-binding) (using `<=`) and Bidirectional (Two-Way) [Data-Binding](#hello-data-binding) (using `<=>`). Dynamic rendering (and re-rendering) of HTML content is also supported via [Content Data-Binding](#hello-content-data-binding). And, modular design is supported with [Glimmer Web Components](#hello-component). You can finally live in pure Rubyland on the Web in both the frontend and backend with [Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web)!
 
 **Hello, World! Sample**
 
@@ -416,141 +414,287 @@ end
 
 @user = User.new
 
-div {
+include Glimmer
+
+Document.ready? do
   div {
-    label('Number of addresses: ', for: 'address-count-field')
-    input(id: 'address-count-field', type: 'number', min: 1, max: 3) {
-      value <=> [@user, :address_count]
+    div {
+      label('Number of addresses: ', for: 'address-count-field')
+      input(id: 'address-count-field', type: 'number', min: 1, max: 3) {
+        value <=> [@user, :address_count]
+      }
     }
-  }
-  
-  div {
-    # Content Data-Binding is used to dynamically (re)generate content of div
-    # based on changes to @user.addresses, replacing older content on every change
-    content(@user, :addresses) do
-      @user.addresses.each do |address|
-        div {
-          div(style: 'display: grid; grid-auto-columns: 80px 280px;') { |address_div|
-            [:name, :street, :city, :state, :zip].each do |attribute|
-              label(attribute.to_s.capitalize, for: "#{attribute}-field")
-              input(id: "#{attribute}-field", type: 'text') {
-                value <=> [address, attribute]
-              }
-            end
-            
-            div(style: 'grid-column: 1 / span 2;') {
-              inner_text <= [address, :text]
-            }
-            
-            style {
-              <<~CSS
-                #{address_div.selector} {
-                  margin: 10px 0;
-                }
-                #{address_div.selector} * {
-                  margin: 5px;
-                }
-                #{address_div.selector} label {
-                  grid-column: 1;
-                }
-                #{address_div.selector} input, #{address_div.selector} select {
-                  grid-column: 2;
+    
+    div {
+      # Content Data-Binding is used to dynamically (re)generate content of div
+      # based on changes to @user.addresses, replacing older content on every change
+      content(@user, :addresses) do
+        @user.addresses.each do |address|
+          div {
+            div(style: 'display: grid; grid-auto-columns: 80px 280px;') { |address_div|
+              [:name, :street, :city, :state, :zip].each do |attribute|
+                label(attribute.to_s.capitalize, for: "#{attribute}-field")
+                input(id: "#{attribute}-field", type: 'text') {
+                  value <=> [address, attribute]
                 }
-              CSS
+              end
+              
+              div(style: 'grid-column: 1 / span 2;') {
+                inner_text <= [address, :text]
+              }
+              
+              style {
+                <<~CSS
+                  #{address_div.selector} {
+                    margin: 10px 0;
+                  }
+                  #{address_div.selector} * {
+                    margin: 5px;
+                  }
+                  #{address_div.selector} label {
+                    grid-column: 1;
+                  }
+                  #{address_div.selector} input, #{address_div.selector} select {
+                    grid-column: 2;
+                  }
+                CSS
+              }
             }
           }
-        }
+        end
       end
-    end
-  }
-}.render
+    }
+  }.render
+end
 ```
 
 Screenshot:
 
 ![Hello, Content Data-Binding!](/images/glimmer-dsl-web-samples-hello-hello-content-data-binding.gif)
 
-**Button Counter Sample**
+**Hello, Component!**
 
-**UPCOMING (NOT RELEASED OR SUPPORTED YET)**
+You can define Glimmer web components (View components) to reuse visual concepts to your heart's content,
+by simply defining a class with `include Glimmer::Web::Component` and encasing the reusable markup inside
+a `markup {...}` block. Glimmer web components automatically extend the Glimmer GUI DSL with new keywords
+that match the underscored versions of the component class names (e.g. a `OrderSummary` class yields
+the `order_summary` keyword for reusing that component within the Glimmer GUI DSL).
+You may also insert a Glimmer component anywhere into a Rails application View using
+`glimmer_component(component_path, *args)` Rails helper. Add `include GlimmerHelper` to `ApplicationHelper`
+or another Rails helper, and use `<%= glimmer_component("path/to/component", *args) %>` in Views.
+Below, we define an `AddressForm` component that generates a `address_form` keyword, and then we
+reuse it twice inside an `AddressPage` component displaying a Shipping Address and a Billing Address.
 
-Glimmer GUI code demonstrating MVC + Glimmer Web Components (Views) + Data-Binding:
+Glimmer GUI code:
 
 ```ruby
 require 'glimmer-dsl-web'
 
-class Counter
-  attr_accessor :count
-
-  def initialize
-    self.count = 0
+Address = Struct.new(:full_name, :street, :street2, :city, :state, :zip_code, keyword_init: true) do
+  STATES = {
+    "AK"=>"Alaska",
+    "AL"=>"Alabama",
+    "AR"=>"Arkansas",
+    "AS"=>"American Samoa",
+    "AZ"=>"Arizona",
+    "CA"=>"California",
+    "CO"=>"Colorado",
+    "CT"=>"Connecticut",
+    "DC"=>"District of Columbia",
+    "DE"=>"Delaware",
+    "FL"=>"Florida",
+    "GA"=>"Georgia",
+    "GU"=>"Guam",
+    "HI"=>"Hawaii",
+    "IA"=>"Iowa",
+    "ID"=>"Idaho",
+    "IL"=>"Illinois",
+    "IN"=>"Indiana",
+    "KS"=>"Kansas",
+    "KY"=>"Kentucky",
+    "LA"=>"Louisiana",
+    "MA"=>"Massachusetts",
+    "MD"=>"Maryland",
+    "ME"=>"Maine",
+    "MI"=>"Michigan",
+    "MN"=>"Minnesota",
+    "MO"=>"Missouri",
+    "MS"=>"Mississippi",
+    "MT"=>"Montana",
+    "NC"=>"North Carolina",
+    "ND"=>"North Dakota",
+    "NE"=>"Nebraska",
+    "NH"=>"New Hampshire",
+    "NJ"=>"New Jersey",
+    "NM"=>"New Mexico",
+    "NV"=>"Nevada",
+    "NY"=>"New York",
+    "OH"=>"Ohio",
+    "OK"=>"Oklahoma",
+    "OR"=>"Oregon",
+    "PA"=>"Pennsylvania",
+    "PR"=>"Puerto Rico",
+    "RI"=>"Rhode Island",
+    "SC"=>"South Carolina",
+    "SD"=>"South Dakota",
+    "TN"=>"Tennessee",
+    "TX"=>"Texas",
+    "UT"=>"Utah",
+    "VA"=>"Virginia",
+    "VI"=>"Virgin Islands",
+    "VT"=>"Vermont",
+    "WA"=>"Washington",
+    "WI"=>"Wisconsin",
+    "WV"=>"West Virginia",
+    "WY"=>"Wyoming"
+  }
+  
+  def state_code
+    STATES.invert[state]
+  end
+  
+  def state_code=(value)
+    self.state = STATES[value]
   end
 
-  def increment!
-    self.count += 1
+  def summary
+    to_h.values.map(&:to_s).reject(&:empty?).join(', ')
   end
 end
 
-class HelloButton
+# AddressForm Glimmer Web Component (View component)
+#
+# Including Glimmer::Web::Component makes this class a View component and automatically
+# generates a new Glimmer GUI DSL keyword that matches the lowercase underscored version
+# of the name of the class. AddressForm generates address_form keyword, which can be used
+# elsewhere in Glimmer GUI DSL code as done inside AddressPage below.
+class AddressForm
   include Glimmer::Web::Component
   
-  before_render do
-    @counter = Counter.new
-  end
+  option :address
+  
+  # Optionally, you can execute code before rendering markup.
+  # This is useful for pre-setup of variables (e.g. Models) that you would use in the markup.
+  #
+  # before_render do
+  # end
   
+  # Optionally, you can execute code after rendering markup.
+  # This is useful for post-setup of extra Model listeners that would interact with the
+  # markup elements and expect them to be rendered already.
+  #
+  # after_render do
+  # end
+  
+  # markup block provides the content of the
   markup {
-    # This will hook into element #app-container and then build HTML inside it using Ruby DSL code
-    div(parent: parent_selector) {
-      text 'Button Counter'
-      
-      button {
-        # Unidirectional Data-Binding indicating that on every change to @counter.count, the value
-        # is read and converted to "Click To Increment: #{value}  ", and then automatically
-        # copied to button innerText (content) to display to the user
-        inner_text <= [@counter, :count, on_read: ->(value) { "Click To Increment: #{value}  " }]
+    div {
+      div(style: 'display: grid; grid-auto-columns: 80px 260px;') { |address_div|
+        label('Full Name: ', for: 'full-name-field')
+        input(id: 'full-name-field') {
+          value <=> [address, :full_name]
+        }
         
-        onclick {
-          @counter.increment!
+        @somelabel = label('Street: ', for: 'street-field')
+        input(id: 'street-field') {
+          value <=> [address, :street]
+        }
+        
+        label('Street 2: ', for: 'street2-field')
+        textarea(id: 'street2-field') {
+          value <=> [address, :street2]
+        }
+        
+        label('City: ', for: 'city-field')
+        input(id: 'city-field') {
+          value <=> [address, :city]
+        }
+        
+        label('State: ', for: 'state-field')
+        select(id: 'state-field') {
+          Address::STATES.each do |state_code, state|
+            option(value: state_code) { state }
+          end
+
+          value <=> [address, :state_code]
+        }
+        
+        label('Zip Code: ', for: 'zip-code-field')
+        input(id: 'zip-code-field', type: 'number', min: '0', max: '99999') {
+          value <=> [address, :zip_code,
+                      on_write: :to_s,
+                    ]
+        }
+        
+        style {
+          <<~CSS
+            #{address_div.selector} * {
+              margin: 5px;
+            }
+            #{address_div.selector} input, #{address_div.selector} select {
+              grid-column: 2;
+            }
+          CSS
         }
       }
+      
+      div(style: 'margin: 5px') {
+        inner_text <= [address, :summary,
+                        computed_by: address.members + ['state_code'],
+                      ]
+      }
     }
   }
 end
 
-HelloButton.render('#app-container')
-```
-
-That produces:
-
-```html
-<div id="application">
-  <button>
-    Click To Increment: 0
-  </button>
-</div>
-```
-
-When clicked:
-
-```html
-<div id="application">
-  <button>
-    Click To Increment: 1
-  </button>
-</div>
-```
-
-When clicked 7 times:
+# AddressPage Glimmer Web Component (View component)
+#
+# This View component represents the main page being rendered,
+# as done by its `render` class method below
+class AddressPage
+  include Glimmer::Web::Component
+  
+  before_render do
+    @shipping_address = Address.new(
+      full_name: 'Johnny Doe',
+      street: '3922 Park Ave',
+      street2: 'PO BOX 8382',
+      city: 'San Diego',
+      state: 'California',
+      zip_code: '91913',
+    )
+    @billing_address = Address.new(
+      full_name: 'John C Doe',
+      street: '123 Main St',
+      street2: 'Apartment 3C',
+      city: 'San Diego',
+      state: 'California',
+      zip_code: '91911',
+    )
+  end
+  
+  markup {
+    div {
+      h1('Shipping Address')
+      
+      address_form(address: @shipping_address)
+      
+      h1('Billing Address')
+      
+      address_form(address: @billing_address)
+    }
+  }
+end
 
-```html
-<div id="application">
-  <button>
-    Click To Increment: 7
-  </button>
-</div>
+Document.ready? do
+  # renders a top-level (root) AddressPage component
+  AddressPage.render
+end
 ```
 
+Screenshot:
 
+![Hello, Component!](/images/glimmer-dsl-web-samples-hello-hello-component.png)
 
 NOTE: Glimmer DSL for Web is an Early Alpha project. If you want it developed faster, please [open an issue report](https://github.com/AndyObtiva/glimmer-dsl-web/issues/new). I have completed some GitHub project features much faster before due to [issue reports](https://github.com/AndyObtiva/glimmer-dsl-web/issues) and [pull requests](https://github.com/AndyObtiva/glimmer-dsl-web/pulls). Please help make better by contributing, adopting for small or low risk projects, and providing feedback. It is still an early alpha, so the more feedback and issues you report the better.
 
@@ -575,6 +719,7 @@ Learn more about the differences between various [Glimmer](https://github.com/An
       - [Hello, Form!](#hello-form)
       - [Hello, Data-Binding!](#hello-data-binding)
       - [Hello, Content Data-Binding!](#hello-content-data-binding)
+      - [Hello, Component!](#hello-content-data-binding)
       - [Hello, Input (Date/Time)!](#hello-input-datetime)
       - [Button Counter](#button-counter)
   - [Glimmer Process](#glimmer-process)
@@ -621,7 +766,7 @@ rails new glimmer_app_server
 Add the following to `Gemfile`:
 
 ```
-gem 'glimmer-dsl-web', '~> 0.0.8'
+gem 'glimmer-dsl-web', '~> 0.0.10'
 ```
 
 Run:
@@ -630,15 +775,25 @@ Run:
 bundle
 ```
 
+(run `rm -rf tmp/cache` from inside your Rails app if you upgrade your `glimmer-dsl-web` gem version from an older one to clear Opal-Rails's cache)
+
 Follow [opal-rails](https://github.com/opal/opal-rails) instructions, basically running:
 
 ```
 bin/rails g opal:install
 ```
 
-Edit `config/initializers/assets.rb` and add the following at the bottom:
-```
+To enable the `glimmer-dsl-web` library in the frontend, edit `config/initializers/assets.rb` and add the following at the bottom:
+
+```ruby
 Opal.use_gem 'glimmer-dsl-web'
+Opal.append_path Rails.root.join('app', 'assets', 'opal')
+```
+
+To enable Opal Browser Debugging in Ruby with the [Source Maps](https://opalrb.com/docs/guides/v1.4.1/source_maps.html) feature, edit `config/initializers/opal.rb` and add the following inside the `Rails.application.configure do; end` block at the bottom of it:
+
+```ruby
+  config.assets.debug = true
 ```
 
 Run:
@@ -660,17 +815,22 @@ mount Glimmer::Engine => "/glimmer" # add on top
 root to: 'welcomes#index'
 ```
 
-Edit `app/views/layouts/application.html.erb` and add the following below other `stylesheet_link_tag` declarations:
-
-```erb
-<%= stylesheet_link_tag    'glimmer/glimmer', media: 'all', 'data-turbolinks-track': 'reload' %>
-```
-
 Clear the file `app/views/welcomes/index.html.erb` completely from all content.
 
 Delete `app/javascript/application.js`
 
-Edit and replace `app/assets/javascript/application.js.rb` content with code below (optionally including a require statement for one of the [samples](#samples) below):
+Rename `app/assets/javascript` directory to `app/assets/opal`.
+
+Add the following lines to `app/assets/config/manifest.js` (and delete their `javascript` equivalents):
+
+```js
+//= link_tree ../../opal .js
+//= link_directory ../opal .js
+```
+
+Rename `app/assets/opal/application.js.rb` to `app/assets/opal/application.rb`.
+
+Edit and replace `app/assets/opal/application.rb` content with code below (optionally including a require statement for one of the [samples](#samples) below inside a `Document.ready? do; end` block):
 
 ```ruby
 require 'glimmer-dsl-web' # brings opal and other dependencies automatically
@@ -680,15 +840,6 @@ require 'glimmer-dsl-web' # brings opal and other dependencies automatically
 
 Example to confirm setup is working:
 
-Initial HTML Markup:
-
-```html
-...
-<div id="app-container">
-</div>
-...
-```
-
 Glimmer GUI code:
 
 ```ruby
@@ -710,13 +861,11 @@ That produces:
 
 ```html
 ...
-<div id="app-container">
-  <div data-parent="#app-container" class="element element-1">
+  <div data-parent="body" class="element element-1">
     <label class="greeting element element-2">
       Hello, World!
     </label>
   </div>
-</div>
 ...
 ```
 
@@ -731,6 +880,22 @@ You should see:
 
 ![setup is working](/images/glimmer-dsl-web-setup-example-working.png)
 
+You may also insert a Glimmer component anywhere into a Rails application View using `glimmer_component(component_path, *args)` Rails helper. Add `include GlimmerHelper` to `ApplicationHelper` or another Rails helper, and use `<%= glimmer_component("path/to/component", *args) %>` in Views.
+
+To use `glimmer_component`, edit `app/helpers/application_helper.rb` in your Rails application, add `require 'glimmer/helpers/glimmer_helper'` on top and `include GlimmerHelper` inside `module`.
+
+`app/helpers/application_helper.rb` should look like this after the change:
+
+```ruby
+require 'glimmer/helpers/glimmer_helper'
+
+module ApplicationHelper
+  # ...
+  include GlimmerHelper
+  # ...
+end
+```
+
 If you run into any issues in setup, refer to the [Sample Glimmer DSL for Web Rails 7 App](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app) project (in case I forgot to include some setup steps by mistake).
 
 Otherwise, if you still cannot setup successfully (even with the help of the sample project, or if the sample project stops working), please do not hesitate to report an [Issue request](https://github.com/AndyObtiva/glimmer-dsl-web/issues) or fix and submit a [Pull Request](https://github.com/AndyObtiva/glimmer-dsl-web/pulls).
@@ -760,7 +925,7 @@ Disable the `webpacker` gem line in `Gemfile`:
 Add the following to `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-web', '~> 0.0.8'
+gem 'glimmer-dsl-web', '~> 0.0.10'
 ```
 
 Run:
@@ -769,15 +934,25 @@ Run:
 bundle
 ```
 
+(run `rm -rf tmp/cache` from inside your Rails app if you upgrade your `glimmer-dsl-web` gem version from an older one to clear Opal-Rails's cache)
+
 Follow [opal-rails](https://github.com/opal/opal-rails) instructions, basically running:
 
 ```
 bin/rails g opal:install
 ```
 
-Edit `config/initializers/assets.rb` and add the following at the bottom:
-```
+To enable the `glimmer-dsl-web` library in the frontend, edit `config/initializers/assets.rb` and add the following at the bottom:
+
+```ruby
 Opal.use_gem 'glimmer-dsl-web'
+Opal.append_path Rails.root.join('app', 'assets', 'opal')
+```
+
+To enable Opal Browser Debugging in Ruby with the [Source Maps](https://opalrb.com/docs/guides/v1.4.1/source_maps.html) feature, edit `config/initializers/opal.rb` and add the following inside the `Rails.application.configure do; end` block at the bottom of it:
+
+```ruby
+  config.assets.debug = true
 ```
 
 Run:
@@ -798,11 +973,6 @@ Add the following to `config/routes.rb` inside the `Rails.application.routes.dra
 mount Glimmer::Engine => "/glimmer" # add on top
 root to: 'welcomes#index'
 ```
-
-Edit `app/views/layouts/application.html.erb` and add the following below other `stylesheet_link_tag` declarations:
-
-```erb
-<%= stylesheet_link_tag 'glimmer/glimmer', media: 'all', 'data-turbolinks-track': 'reload' %>
 ```
 
 Also, delete the following line:
@@ -813,7 +983,18 @@ Also, delete the following line:
 
 Clear the file `app/views/welcomes/index.html.erb` completely from all content.
 
-Edit and replace `app/assets/javascript/application.js.rb` content with code below (optionally including a require statement for one of the [samples](#samples) below):
+Rename `app/assets/javascript` directory to `app/assets/opal`.
+
+Add the following lines to `app/assets/config/manifest.js` (and delete their `javascript` equivalents):
+
+```js
+//= link_tree ../../opal .js
+//= link_directory ../opal .js
+```
+
+Rename `app/assets/opal/application.js.rb` to `app/assets/opal/application.rb`.
+
+Edit and replace `app/assets/opal/application.rb` content with code below (optionally including a require statement for one of the [samples](#samples) below inside a `Document.ready? do; end` block):
 
 ```ruby
 require 'glimmer-dsl-web' # brings opal and other dependencies automatically
@@ -874,6 +1055,22 @@ You should see:
 
 ![setup is working](/images/glimmer-dsl-web-setup-example-working.png)
 
+You may also insert a Glimmer component anywhere into a Rails application View using `glimmer_component(component_path, *args)` Rails helper. Add `include GlimmerHelper` to `ApplicationHelper` or another Rails helper, and use `<%= glimmer_component("path/to/component", *args) %>` in Views.
+
+To use `glimmer_component`, edit `app/helpers/application_helper.rb` in your Rails application, add `require 'glimmer/helpers/glimmer_helper'` on top and `include GlimmerHelper` inside `module`.
+
+`app/helpers/application_helper.rb` should look like this after the change:
+
+```ruby
+require 'glimmer/helpers/glimmer_helper'
+
+module ApplicationHelper
+  # ...
+  include GlimmerHelper
+  # ...
+end
+```
+
 **NOT RELEASED OR SUPPORTED YET**
 
 If you run into any issues in setup, refer to the [Sample Glimmer DSL for Web Rails 6 App](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails6-app) project (in case I forgot to include some setup steps by mistake).
@@ -886,7 +1083,7 @@ Glimmer DSL for Web offers a GUI DSL for building HTML Web User Interfaces decla
 
 1- **Keywords (HTML Elements)**
 
-You can declare any HTML element by simply using the lowercase underscored version of its name (Ruby convention for method names) like `div`, `span`, `form`, `input`, `button`, `table`, `tr`, `th`, and `td`.
+You can declare any HTML element by simply using the lowercase version of its name (Ruby convention for method names) like `div`, `span`, `form`, `input`, `button`, `table`, `tr`, `th`, and `td`.
 
 Under the hood, HTML element DSL keywords are invoked as Ruby methods.
 
@@ -1022,6 +1219,8 @@ That produces the following under `<body></body>`:
 
 #### Hello, Button!
 
+Event listeners can be setup on any element using the same event names used in HTML (e.g. `onclick`) while passing in a standard Ruby block to handle behavior. `$$` gives access to `window` to invoke functions like `alert`.
+
 Glimmer GUI code:
 
 ```ruby
@@ -1054,6 +1253,8 @@ Screenshot:
 
 #### Hello, Form!
 
+[Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) gives access to all Web Browser built-in features like HTML form validations, input focus, events, and element functions from a very terse and productive Ruby GUI DSL.
+
 Glimmer GUI code:
 
 ```ruby
@@ -1207,6 +1408,8 @@ Screenshot:
 
 #### Hello, Data-Binding!
 
+[Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) intuitively supports both Unidirectional (One-Way) Data-Binding via the `<=` operator and Bidirectional (Two-Way) Data-Binding via the `<=>` operator, incredibly simplifying how to sync View properties with Model attributes with the simplest code to reason about.
+
 Glimmer GUI code:
 
 ```ruby
@@ -1378,6 +1581,10 @@ Screenshot:
 
 #### Hello, Content Data-Binding!
 
+If you need to regenerate HTML element content dynamically, you can use Content Data-Binding to effortlessly
+rebuild HTML elements based on changes in a Model attribute that provides the source data.
+In this example, we generate multiple address forms based on the number of addresses the user has.
+
 Glimmer GUI code:
 
 ```ruby
@@ -1449,59 +1656,287 @@ end
 
 @user = User.new
 
-div {
+include Glimmer
+
+Document.ready? do
   div {
-    label('Number of addresses: ', for: 'address-count-field')
-    input(id: 'address-count-field', type: 'number', min: 1, max: 3) {
-      value <=> [@user, :address_count]
+    div {
+      label('Number of addresses: ', for: 'address-count-field')
+      input(id: 'address-count-field', type: 'number', min: 1, max: 3) {
+        value <=> [@user, :address_count]
+      }
+    }
+    
+    div {
+      # Content Data-Binding is used to dynamically (re)generate content of div
+      # based on changes to @user.addresses, replacing older content on every change
+      content(@user, :addresses) do
+        @user.addresses.each do |address|
+          div {
+            div(style: 'display: grid; grid-auto-columns: 80px 280px;') { |address_div|
+              [:name, :street, :city, :state, :zip].each do |attribute|
+                label(attribute.to_s.capitalize, for: "#{attribute}-field")
+                input(id: "#{attribute}-field", type: 'text') {
+                  value <=> [address, attribute]
+                }
+              end
+              
+              div(style: 'grid-column: 1 / span 2;') {
+                inner_text <= [address, :text]
+              }
+              
+              style {
+                <<~CSS
+                  #{address_div.selector} {
+                    margin: 10px 0;
+                  }
+                  #{address_div.selector} * {
+                    margin: 5px;
+                  }
+                  #{address_div.selector} label {
+                    grid-column: 1;
+                  }
+                  #{address_div.selector} input, #{address_div.selector} select {
+                    grid-column: 2;
+                  }
+                CSS
+              }
+            }
+          }
+        end
+      end
     }
+  }.render
+end
+```
+
+Screenshot:
+
+![Hello, Content Data-Binding!](/images/glimmer-dsl-web-samples-hello-hello-content-data-binding.gif)
+
+#### Hello, Component!
+
+You can define Glimmer web components (View components) to reuse visual concepts to your heart's content,
+by simply defining a class with `include Glimmer::Web::Component` and encasing the reusable markup inside
+a `markup {...}` block. Glimmer web components automatically extend the Glimmer GUI DSL with new keywords
+that match the underscored versions of the component class names (e.g. a `OrderSummary` class yields
+the `order_summary` keyword for reusing that component within the Glimmer GUI DSL).
+You may also insert a Glimmer component anywhere into a Rails application View using
+`glimmer_component(component_path, *args)` Rails helper. Add `include GlimmerHelper` to `ApplicationHelper`
+or another Rails helper, and use `<%= glimmer_component("path/to/component", *args) %>` in Views.
+Below, we define an `AddressForm` component that generates a `address_form` keyword, and then we
+reuse it twice inside an `AddressPage` component displaying a Shipping Address and a Billing Address.
+
+Glimmer GUI code:
+
+```ruby
+require 'glimmer-dsl-web'
+
+Address = Struct.new(:full_name, :street, :street2, :city, :state, :zip_code, keyword_init: true) do
+  STATES = {
+    "AK"=>"Alaska",
+    "AL"=>"Alabama",
+    "AR"=>"Arkansas",
+    "AS"=>"American Samoa",
+    "AZ"=>"Arizona",
+    "CA"=>"California",
+    "CO"=>"Colorado",
+    "CT"=>"Connecticut",
+    "DC"=>"District of Columbia",
+    "DE"=>"Delaware",
+    "FL"=>"Florida",
+    "GA"=>"Georgia",
+    "GU"=>"Guam",
+    "HI"=>"Hawaii",
+    "IA"=>"Iowa",
+    "ID"=>"Idaho",
+    "IL"=>"Illinois",
+    "IN"=>"Indiana",
+    "KS"=>"Kansas",
+    "KY"=>"Kentucky",
+    "LA"=>"Louisiana",
+    "MA"=>"Massachusetts",
+    "MD"=>"Maryland",
+    "ME"=>"Maine",
+    "MI"=>"Michigan",
+    "MN"=>"Minnesota",
+    "MO"=>"Missouri",
+    "MS"=>"Mississippi",
+    "MT"=>"Montana",
+    "NC"=>"North Carolina",
+    "ND"=>"North Dakota",
+    "NE"=>"Nebraska",
+    "NH"=>"New Hampshire",
+    "NJ"=>"New Jersey",
+    "NM"=>"New Mexico",
+    "NV"=>"Nevada",
+    "NY"=>"New York",
+    "OH"=>"Ohio",
+    "OK"=>"Oklahoma",
+    "OR"=>"Oregon",
+    "PA"=>"Pennsylvania",
+    "PR"=>"Puerto Rico",
+    "RI"=>"Rhode Island",
+    "SC"=>"South Carolina",
+    "SD"=>"South Dakota",
+    "TN"=>"Tennessee",
+    "TX"=>"Texas",
+    "UT"=>"Utah",
+    "VA"=>"Virginia",
+    "VI"=>"Virgin Islands",
+    "VT"=>"Vermont",
+    "WA"=>"Washington",
+    "WI"=>"Wisconsin",
+    "WV"=>"West Virginia",
+    "WY"=>"Wyoming"
   }
   
-  div {
-    # Content Data-Binding is used to dynamically (re)generate content of div
-    # based on changes to @user.addresses, replacing older content on every change
-    content(@user, :addresses) do
-      @user.addresses.each do |address|
-        div {
-          div(style: 'display: grid; grid-auto-columns: 80px 280px;') { |address_div|
-            [:name, :street, :city, :state, :zip].each do |attribute|
-              label(attribute.to_s.capitalize, for: "#{attribute}-field")
-              input(id: "#{attribute}-field", type: 'text') {
-                value <=> [address, attribute]
-              }
-            end
-            
-            div(style: 'grid-column: 1 / span 2;') {
-              inner_text <= [address, :text]
+  def state_code
+    STATES.invert[state]
+  end
+  
+  def state_code=(value)
+    self.state = STATES[value]
+  end
+
+  def summary
+    to_h.values.map(&:to_s).reject(&:empty?).join(', ')
+  end
+end
+
+# AddressForm Glimmer Web Component (View component)
+#
+# Including Glimmer::Web::Component makes this class a View component and automatically
+# generates a new Glimmer GUI DSL keyword that matches the lowercase underscored version
+# of the name of the class. AddressForm generates address_form keyword, which can be used
+# elsewhere in Glimmer GUI DSL code as done inside AddressPage below.
+class AddressForm
+  include Glimmer::Web::Component
+  
+  option :address
+  
+  # Optionally, you can execute code before rendering markup.
+  # This is useful for pre-setup of variables (e.g. Models) that you would use in the markup.
+  #
+  # before_render do
+  # end
+  
+  # Optionally, you can execute code after rendering markup.
+  # This is useful for post-setup of extra Model listeners that would interact with the
+  # markup elements and expect them to be rendered already.
+  #
+  # after_render do
+  # end
+  
+  # markup block provides the content of the
+  markup {
+    div {
+      div(style: 'display: grid; grid-auto-columns: 80px 260px;') { |address_div|
+        label('Full Name: ', for: 'full-name-field')
+        input(id: 'full-name-field') {
+          value <=> [address, :full_name]
+        }
+        
+        @somelabel = label('Street: ', for: 'street-field')
+        input(id: 'street-field') {
+          value <=> [address, :street]
+        }
+        
+        label('Street 2: ', for: 'street2-field')
+        textarea(id: 'street2-field') {
+          value <=> [address, :street2]
+        }
+        
+        label('City: ', for: 'city-field')
+        input(id: 'city-field') {
+          value <=> [address, :city]
+        }
+        
+        label('State: ', for: 'state-field')
+        select(id: 'state-field') {
+          Address::STATES.each do |state_code, state|
+            option(value: state_code) { state }
+          end
+
+          value <=> [address, :state_code]
+        }
+        
+        label('Zip Code: ', for: 'zip-code-field')
+        input(id: 'zip-code-field', type: 'number', min: '0', max: '99999') {
+          value <=> [address, :zip_code,
+                      on_write: :to_s,
+                    ]
+        }
+        
+        style {
+          <<~CSS
+            #{address_div.selector} * {
+              margin: 5px;
             }
-            
-            style {
-              <<~CSS
-                #{address_div.selector} {
-                  margin: 10px 0;
-                }
-                #{address_div.selector} * {
-                  margin: 5px;
-                }
-                #{address_div.selector} label {
-                  grid-column: 1;
-                }
-                #{address_div.selector} input, #{address_div.selector} select {
-                  grid-column: 2;
-                }
-              CSS
+            #{address_div.selector} input, #{address_div.selector} select {
+              grid-column: 2;
             }
-          }
+          CSS
         }
-      end
-    end
+      }
+      
+      div(style: 'margin: 5px') {
+        inner_text <= [address, :summary,
+                        computed_by: address.members + ['state_code'],
+                      ]
+      }
+    }
+  }
+end
+
+# AddressPage Glimmer Web Component (View component)
+#
+# This View component represents the main page being rendered,
+# as done by its `render` class method below
+class AddressPage
+  include Glimmer::Web::Component
+  
+  before_render do
+    @shipping_address = Address.new(
+      full_name: 'Johnny Doe',
+      street: '3922 Park Ave',
+      street2: 'PO BOX 8382',
+      city: 'San Diego',
+      state: 'California',
+      zip_code: '91913',
+    )
+    @billing_address = Address.new(
+      full_name: 'John C Doe',
+      street: '123 Main St',
+      street2: 'Apartment 3C',
+      city: 'San Diego',
+      state: 'California',
+      zip_code: '91911',
+    )
+  end
+  
+  markup {
+    div {
+      h1('Shipping Address')
+      
+      address_form(address: @shipping_address)
+      
+      h1('Billing Address')
+      
+      address_form(address: @billing_address)
+    }
   }
-}.render
+end
+
+Document.ready? do
+  # renders a top-level (root) AddressPage component
+  AddressPage.render
+end
 ```
 
 Screenshot:
 
-![Hello, Content Data-Binding!](/images/glimmer-dsl-web-samples-hello-hello-content-data-binding.gif)
+![Hello, Component!](/images/glimmer-dsl-web-samples-hello-hello-component.png)
 
 #### Hello, Input (Date/Time)!
 
@@ -1657,7 +2092,7 @@ class HelloButton
   }
 end
 
-HelloButton.render('#app-container')
+HelloButton.render
 ```
 
 That produces: