glimmer-dsl-web 0.0.7 → 0.0.9

data/README.md

@@ -1,9 +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.7 (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.9 (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, and most straight-forward 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 `<=>`). 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)!
+[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**
 
@@ -337,87 +337,361 @@ Screenshot:
 
 ![Hello, Data-Binding!](/images/glimmer-dsl-web-samples-hello-hello-data-binding.gif)
 
-**Button Counter Sample**
+**Hello, Content Data-Binding!**
 
-**UPCOMING (NOT RELEASED OR SUPPORTED YET)**
+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 demonstrating MVC + Glimmer Web Components (Views) + Data-Binding:
+Glimmer GUI code:
 
 ```ruby
 require 'glimmer-dsl-web'
 
-class Counter
-  attr_accessor :count
+class Address
+  attr_accessor :text
+  attr_reader :name, :street, :city, :state, :zip
+  
+  def name=(value)
+    @name = value
+    update_text
+  end
+  
+  def street=(value)
+    @street = value
+    update_text
+  end
+  
+  def city=(value)
+    @city = value
+    update_text
+  end
+  
+  def state=(value)
+    @state = value
+    update_text
+  end
+  
+  def zip=(value)
+    @zip = value
+    update_text
+  end
+  
+  private
+  
+  def update_text
+    self.text = [name, street, city, state, zip].compact.reject(&:empty?).join(', ')
+  end
+end
 
+class User
+  attr_accessor :addresses
+  attr_reader :address_count
+  
   def initialize
-    self.count = 0
+    @address_count = 1
+    @addresses = []
+    update_addresses
+  end
+  
+  def address_count=(value)
+    value = [[1, value.to_i].max, 3].min
+    @address_count = value
+    update_addresses
+  end
+  
+  private
+  
+  def update_addresses
+    address_count_change = address_count - addresses.size
+    if address_count_change > 0
+      address_count_change.times { addresses << Address.new }
+    else
+      address_count_change.abs.times { addresses.pop }
+    end
   end
+end
 
-  def increment!
-    self.count += 1
+@user = User.new
+
+include Glimmer
+
+Document.ready? do
+  div {
+    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).
+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"
+  }
+  
+  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
 
-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.
 
@@ -441,6 +715,8 @@ Learn more about the differences between various [Glimmer](https://github.com/An
       - [Hello, Button!](#hello-button)
       - [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)
@@ -487,13 +763,7 @@ rails new glimmer_app_server
 Add the following to `Gemfile`:
 
 ```
-gem 'opal', '1.4.1'
-gem 'opal-rails', '2.0.2'
-gem 'opal-async', '~> 1.4.0'
-gem 'opal-jquery', '~> 0.4.6'
-gem 'glimmer-dsl-web', '~> 0.0.7'
-gem 'glimmer-dsl-xml', '~> 1.3.1', require: false
-gem 'glimmer-dsl-css', '~> 1.2.1', require: false
+gem 'glimmer-dsl-web', '~> 0.0.9'
 ```
 
 Run:
@@ -508,11 +778,18 @@ Follow [opal-rails](https://github.com/opal/opal-rails) instructions, basically
 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'
 ```
 
+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:
 
 ```
@@ -532,12 +809,6 @@ 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`
@@ -632,13 +903,7 @@ Disable the `webpacker` gem line in `Gemfile`:
 Add the following to `Gemfile`:
 
 ```ruby
-gem 'opal', '1.4.1'
-gem 'opal-rails', '2.0.2'
-gem 'opal-async', '~> 1.4.0'
-gem 'opal-jquery', '~> 0.4.6'
-gem 'glimmer-dsl-web', '~> 0.0.7'
-gem 'glimmer-dsl-xml', '~> 1.3.1', require: false
-gem 'glimmer-dsl-css', '~> 1.2.1', require: false
+gem 'glimmer-dsl-web', '~> 0.0.9'
 ```
 
 Run:
@@ -653,11 +918,18 @@ Follow [opal-rails](https://github.com/opal/opal-rails) instructions, basically
 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'
 ```
 
+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:
 
 ```
@@ -676,11 +948,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:
@@ -764,7 +1031,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.
 
@@ -900,6 +1167,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
@@ -932,6 +1201,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
@@ -1085,6 +1356,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
@@ -1254,6 +1527,362 @@ Screenshot:
 
 ![Hello, Data-Binding!](/images/glimmer-dsl-web-samples-hello-hello-data-binding.gif)
 
+#### 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
+require 'glimmer-dsl-web'
+
+class Address
+  attr_accessor :text
+  attr_reader :name, :street, :city, :state, :zip
+  
+  def name=(value)
+    @name = value
+    update_text
+  end
+  
+  def street=(value)
+    @street = value
+    update_text
+  end
+  
+  def city=(value)
+    @city = value
+    update_text
+  end
+  
+  def state=(value)
+    @state = value
+    update_text
+  end
+  
+  def zip=(value)
+    @zip = value
+    update_text
+  end
+  
+  private
+  
+  def update_text
+    self.text = [name, street, city, state, zip].compact.reject(&:empty?).join(', ')
+  end
+end
+
+class User
+  attr_accessor :addresses
+  attr_reader :address_count
+  
+  def initialize
+    @address_count = 1
+    @addresses = []
+    update_addresses
+  end
+  
+  def address_count=(value)
+    value = [[1, value.to_i].max, 3].min
+    @address_count = value
+    update_addresses
+  end
+  
+  private
+  
+  def update_addresses
+    address_count_change = address_count - addresses.size
+    if address_count_change > 0
+      address_count_change.times { addresses << Address.new }
+    else
+      address_count_change.abs.times { addresses.pop }
+    end
+  end
+end
+
+@user = User.new
+
+include Glimmer
+
+Document.ready? do
+  div {
+    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).
+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"
+  }
+  
+  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;
+            }
+            #{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
+
+# 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
+
+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)
+
 #### Hello, Input (Date/Time)!
 
 Glimmer GUI code:
@@ -1408,7 +2037,7 @@ class HelloButton
   }
 end
 
-HelloButton.render('#app-container')
+HelloButton.render
 ```
 
 That produces: