glimmer-dsl-web 0.0.10 → 0.0.11

data/README.md

@@ -1,4 +1,4 @@
-# [<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)
+# [<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.11 (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)
@@ -220,6 +220,86 @@ Screenshot:
 
 ![Hello, Form!](/images/glimmer-dsl-web-samples-hello-hello-form.gif)
 
+**Hello, Observer!**
+
+[Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) provides the `observe(model, attribute) { ... }` keyword to employ the [Observer Design Pattern](https://en.wikipedia.org/wiki/Observer_pattern) as per [MVC](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) (Model View Controller), enabling Views to observe Models and update themselves in response to changes. If the `observe` keyword is used from inside a [Component](#hello-component) (covered later), when the Component is removed or its top-level element is removed, the observer is automatically cleaned up. The need for such explicit observers is significantly diminished by the availablility of the more advanced Unidirectional [Data-Binding](#hello-data-binding) Support and Bidirectional [Data-Binding](#hello-data-binding) Support (covered later).
+
+Glimmer GUI code:
+
+```ruby
+require 'glimmer-dsl-web'
+
+class NumberHolder
+  attr_accessor :number
+  
+  def initialize
+    self.number = 50
+  end
+end
+
+class HelloObserver
+  include Glimmer::Web::Component
+  
+  before_render do
+    @number_holder = NumberHolder.new
+  end
+  
+  after_render do
+    # observe Model attribute @number_holder.number for changes and update View
+    observe(@number_holder, :number) do
+      number_string = @number_holder.number.to_s
+      @number_input.value = number_string unless @number_input.value == number_string
+      @range_input.value = number_string unless @range_input.value == number_string
+    end
+    # Bidirectional Data-Binding does the same thing automatically
+    # Just disable the observe block above as well as the oninput listeners below
+    # and enable the `value <=> [@number_holder, :number]` lines to try the data-binding version
+    # Learn more about Bidirectional and Unidirectional Data-Binding in hello_data_binding.rb
+  end
+  
+  markup {
+    div {
+      div {
+        @number_input = input(type: 'number', value: @number_holder.number, min: 0, max: 100) {
+          # oninput listener updates Model attribute @number_holder.number
+          oninput do
+            @number_holder.number = @number_input.value.to_i
+          end
+          
+          # Bidirectional Data-Binding simplifies the implementation significantly
+          # by enabling the following line and disabling oninput listeners as well
+          # as the after_body observe block observer
+          # Learn more about Bidirectional and Unidirectional Data-Binding in hello_data_binding.rb
+#           value <=> [@number_holder, :number]
+        }
+      }
+      div {
+        @range_input = input(type: 'range', value: @number_holder.number, min: 0, max: 100) {
+          # oninput listener updates Model attribute @number_holder.number
+          oninput do
+            @number_holder.number = @range_input.value.to_i
+          end
+          
+          # Bidirectional Data-Binding simplifies the implementation significantly
+          # by enabling the following line and disabling oninput listeners as well
+          # as the after_body observe block observer
+          # Learn more about Bidirectional and Unidirectional Data-Binding in hello_data_binding.rb
+#           value <=> [@number_holder, :number]
+        }
+      }
+    }
+  }
+end
+
+Document.ready? do
+  HelloObserver.render
+end
+```
+
+Screenshot:
+
+![Hello, Observer!](/images/glimmer-dsl-web-samples-hello-hello-observer.gif)
+
 **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.
@@ -479,9 +559,6 @@ by simply defining a class with `include Glimmer::Web::Component` and encasing t
 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.
 
@@ -696,6 +773,211 @@ Screenshot:
 
 ![Hello, Component!](/images/glimmer-dsl-web-samples-hello-hello-component.png)
 
+**Hello, glimmer_component Rails Helper!**
+
+You may insert a Glimmer component anywhere into a Rails 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.
+
+Rails `ApplicationHelper` setup code:
+
+```ruby
+require 'glimmer/helpers/glimmer_helper'
+
+module ApplicationHelper
+  # ...
+  include GlimmerHelper
+  # ...
+end
+```
+
+Rails View code:
+
+```erb
+<div id="address-container">
+  <h1>Shipping Address </h1>
+  <legend>Please enter your shipping address information (Zip Code must be a valid 5 digit number)</legend>
+  <!-- This sample demonstrates use of glimmer_component helper with arguments -->
+  <%= glimmer_component('address_form',
+        full_name: params[:full_name],
+        street: params[:street],
+        street2: params[:street2],
+        city: params[:city],
+        state: params[:state],
+        zip_code: params[:zip_code]
+      )
+   %>
+   <div>
+     <a href="/">&lt;&lt; Back Home</a>
+   </div>
+</div>
+```
+
+Glimmer GUI code:
+
+```ruby
+require 'glimmer-dsl-web'
+
+class AddressForm
+  Address = Struct.new(:full_name, :street, :street2, :city, :state, :zip_code, keyword_init: true) do
+    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
+  
+  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"
+  }
+
+  include Glimmer::Web::Component
+  
+  option :full_name
+  option :street
+  option :street2
+  option :city
+  option :state
+  option :zip_code
+  
+  attr_reader :address
+  
+  before_render do
+    @address = Address.new(
+      full_name: full_name,
+      street: street,
+      street2: street2,
+      city: city,
+      state: state,
+      zip_code: zip_code,
+    )
+  end
+  
+  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') {
+          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
+```
+
+Screenshot:
+
+![Hello, glimmer_component Rails Helper!](/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.
 
 Learn more about the differences between various [Glimmer](https://github.com/AndyObtiva/glimmer) DSLs by looking at:
@@ -717,9 +999,11 @@ Learn more about the differences between various [Glimmer](https://github.com/An
       - [Hello, World!](#hello-world)
       - [Hello, Button!](#hello-button)
       - [Hello, Form!](#hello-form)
+      - [Hello, Observer!](#hello-observer)
       - [Hello, Data-Binding!](#hello-data-binding)
       - [Hello, Content Data-Binding!](#hello-content-data-binding)
       - [Hello, Component!](#hello-content-data-binding)
+      - [Hello, glimmer_component Rails Helper!](#hello-glimmer_component-rails-helper)
       - [Hello, Input (Date/Time)!](#hello-input-datetime)
       - [Button Counter](#button-counter)
   - [Glimmer Process](#glimmer-process)
@@ -736,10 +1020,8 @@ Learn more about the differences between various [Glimmer](https://github.com/An
 
 [Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) will begin by supporting [Opal Ruby](https://opalrb.com/) on [Rails](https://rubyonrails.org/). [Opal](https://opalrb.com/) is a lightweight Ruby to JavaScript transpiler that results in small downloadables compared to WASM. In the future, the project might grow to support [Ruby WASM](https://github.com/ruby/ruby.wasm) as an alternative to [Opal Ruby](https://opalrb.com/) that could be switched to with a simple configuration change.
 
-- Ruby 3.0 (newer Ruby versions are not supported at this time)
+- Ruby 3.0+
 - Rails 6-7: [https://github.com/rails/rails](https://github.com/rails/rails)
-- Opal 1.4.1 for Rails 6-7: [https://github.com/opal/opal](https://github.com/opal/opal)
-- Opal-Rails 2.0.2 for Rails 6-7: [https://github.com/opal/opal-rails](https://github.com/opal/opal-rails)
 
 ## Setup
 
@@ -766,7 +1048,7 @@ rails new glimmer_app_server
 Add the following to `Gemfile`:
 
 ```
-gem 'glimmer-dsl-web', '~> 0.0.10'
+gem 'glimmer-dsl-web', '~> 0.0.11'
 ```
 
 Run:
@@ -817,7 +1099,7 @@ root to: 'welcomes#index'
 
 Clear the file `app/views/welcomes/index.html.erb` completely from all content.
 
-Delete `app/javascript/application.js`
+Delete `app/javascript` directory
 
 Rename `app/assets/javascript` directory to `app/assets/opal`.
 
@@ -830,7 +1112,7 @@ Add the following lines to `app/assets/config/manifest.js` (and delete their `ja
 
 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):
+Edit and replace `app/assets/opal/application.rb` content with code below (optionally including a require statement for one of the [samples](#samples) below):
 
 ```ruby
 require 'glimmer-dsl-web' # brings opal and other dependencies automatically
@@ -838,6 +1120,22 @@ require 'glimmer-dsl-web' # brings opal and other dependencies automatically
 # Add more require-statements or Glimmer GUI DSL code
 ```
 
+```ruby
+require 'glimmer-dsl-web'
+
+require 'glimmer-dsl-web/samples/hello/hello_world.rb'
+```
+
+If the `<body></body>` element (where the Glimmer GUI DSL adds elements by default) is not available when the JS file is loading, you need to put the code inside a `Document.ready? do; end` (but, it is recommended that you load the JS file after the parent element like `<body></body>` is in the page already for faster performance, which is guaranteed automatically by using `glimmer_component`, mentioned in details below):
+
+```ruby
+require 'glimmer-dsl-web'
+
+Document.ready? do
+  require 'glimmer-dsl-web/samples/hello/hello_world.rb'
+end
+```
+
 Example to confirm setup is working:
 
 Glimmer GUI code:
@@ -849,7 +1147,7 @@ include Glimmer
 
 Document.ready? do
   # This will hook into element #app-container and then build HTML inside it using Ruby DSL code
-  div(parent: '#app-container') {
+  div {
     label(class: 'greeting') {
       'Hello, World!'
     }
@@ -860,13 +1158,13 @@ end
 That produces:
 
 ```html
-...
+<body>
   <div data-parent="body" class="element element-1">
     <label class="greeting element element-2">
       Hello, World!
     </label>
   </div>
-...
+</body>
 ```
 
 Start the Rails server:
@@ -880,7 +1178,48 @@ 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.
+If you want to customize where the top-level element is mounted, just pass a `parent: 'css_selector'` option.
+
+HTML:
+
+```html
+...
+<div id="app-container">
+</div>
+...
+```
+
+Glimmer GUI code:
+
+```ruby
+require 'glimmer-dsl-web'
+
+include Glimmer
+
+Document.ready? do
+  # This will hook into element #app-container and then build HTML inside it using Ruby DSL code
+  div(parent: '#app-container') {
+    label(class: 'greeting') {
+      'Hello, World!'
+    }
+  }.render
+end
+```
+
+That produces:
+
+```html
+...
+<div id="app-container">
+  <div data-parent="app-container" class="element element-1">
+    <label class="greeting element element-2">
+      Hello, World!
+    </label>
+  </div>
+</div>
+...
+```
+You may insert a Glimmer component anywhere into a Rails 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`.
 
@@ -925,7 +1264,7 @@ Disable the `webpacker` gem line in `Gemfile`:
 Add the following to `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-web', '~> 0.0.10'
+gem 'glimmer-dsl-web', '~> 0.0.11'
 ```
 
 Run:
@@ -1055,7 +1394,7 @@ 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.
+You may insert a Glimmer component anywhere into a Rails 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`.
 
@@ -1406,6 +1745,86 @@ Screenshot:
 
 ![Hello, Form!](/images/glimmer-dsl-web-samples-hello-hello-form.gif)
 
+#### Hello, Observer!
+
+[Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) provides the `observe(model, attribute) { ... }` keyword to employ the [Observer Design Pattern](https://en.wikipedia.org/wiki/Observer_pattern) as per [MVC](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) (Model View Controller), enabling Views to observe Models and update themselves in response to changes. If the `observe` keyword is used from inside a [Component](#hello-component) (covered later), when the Component is removed or its top-level element is removed, the observer is automatically cleaned up. The need for such explicit observers is significantly diminished by the availablility of the more advanced Unidirectional [Data-Binding](#hello-data-binding) Support and Bidirectional [Data-Binding](#hello-data-binding) Support (covered later).
+
+Glimmer GUI code:
+
+```ruby
+require 'glimmer-dsl-web'
+
+class NumberHolder
+  attr_accessor :number
+  
+  def initialize
+    self.number = 50
+  end
+end
+
+class HelloObserver
+  include Glimmer::Web::Component
+  
+  before_render do
+    @number_holder = NumberHolder.new
+  end
+  
+  after_render do
+    # observe Model attribute @number_holder.number for changes and update View
+    observe(@number_holder, :number) do
+      number_string = @number_holder.number.to_s
+      @number_input.value = number_string unless @number_input.value == number_string
+      @range_input.value = number_string unless @range_input.value == number_string
+    end
+    # Bidirectional Data-Binding does the same thing automatically
+    # Just disable the observe block above as well as the oninput listeners below
+    # and enable the `value <=> [@number_holder, :number]` lines to try the data-binding version
+    # Learn more about Bidirectional and Unidirectional Data-Binding in hello_data_binding.rb
+  end
+  
+  markup {
+    div {
+      div {
+        @number_input = input(type: 'number', value: @number_holder.number, min: 0, max: 100) {
+          # oninput listener updates Model attribute @number_holder.number
+          oninput do
+            @number_holder.number = @number_input.value.to_i
+          end
+          
+          # Bidirectional Data-Binding simplifies the implementation significantly
+          # by enabling the following line and disabling oninput listeners as well
+          # as the after_body observe block observer
+          # Learn more about Bidirectional and Unidirectional Data-Binding in hello_data_binding.rb
+#           value <=> [@number_holder, :number]
+        }
+      }
+      div {
+        @range_input = input(type: 'range', value: @number_holder.number, min: 0, max: 100) {
+          # oninput listener updates Model attribute @number_holder.number
+          oninput do
+            @number_holder.number = @range_input.value.to_i
+          end
+          
+          # Bidirectional Data-Binding simplifies the implementation significantly
+          # by enabling the following line and disabling oninput listeners as well
+          # as the after_body observe block observer
+          # Learn more about Bidirectional and Unidirectional Data-Binding in hello_data_binding.rb
+#           value <=> [@number_holder, :number]
+        }
+      }
+    }
+  }
+end
+
+Document.ready? do
+  HelloObserver.render
+end
+```
+
+Screenshot:
+
+![Hello, Observer!](/images/glimmer-dsl-web-samples-hello-hello-observer.gif)
+
 #### 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.
@@ -1721,9 +2140,6 @@ by simply defining a class with `include Glimmer::Web::Component` and encasing t
 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.
 
@@ -1938,6 +2354,212 @@ Screenshot:
 
 ![Hello, Component!](/images/glimmer-dsl-web-samples-hello-hello-component.png)
 
+#### Hello, glimmer_component Rails Helper!
+
+You may insert a Glimmer component anywhere into a Rails 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.
+
+Rails `ApplicationHelper` setup code:
+
+```ruby
+require 'glimmer/helpers/glimmer_helper'
+
+module ApplicationHelper
+  # ...
+  include GlimmerHelper
+  # ...
+end
+```
+
+Rails View code:
+
+```erb
+<div id="address-container">
+  <h1>Shipping Address </h1>
+  <legend>Please enter your shipping address information (Zip Code must be a valid 5 digit number)</legend>
+  <!-- This sample demonstrates use of glimmer_component helper with arguments -->
+  <%= glimmer_component('address_form',
+        full_name: params[:full_name],
+        street: params[:street],
+        street2: params[:street2],
+        city: params[:city],
+        state: params[:state],
+        zip_code: params[:zip_code]
+      )
+   %>
+   <div>
+     <a href="/">&lt;&lt; Back Home</a>
+   </div>
+</div>
+```
+
+Glimmer GUI code:
+
+```ruby
+require 'glimmer-dsl-web'
+
+class AddressForm
+  Address = Struct.new(:full_name, :street, :street2, :city, :state, :zip_code, keyword_init: true) do
+    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
+  
+  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"
+  }
+
+  include Glimmer::Web::Component
+  
+  option :full_name
+  option :street
+  option :street2
+  option :city
+  option :state
+  option :zip_code
+  
+  attr_reader :address
+  
+  before_render do
+    @address = Address.new(
+      full_name: full_name,
+      street: street,
+      street2: street2,
+      city: city,
+      state: state,
+      zip_code: zip_code,
+    )
+  end
+  
+  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') {
+          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
+```
+
+Screenshot:
+
+![Hello, glimmer_component Rails Helper!](/images/glimmer-dsl-web-samples-hello-hello-component.png)
+
+
 #### Hello, Input (Date/Time)!
 
 Glimmer GUI code:
@@ -2047,8 +2669,6 @@ Screenshot:
 
 #### Button Counter
 
-**UPCOMING (NOT RELEASED OR SUPPORTED YET)**
-
 Glimmer GUI code demonstrating MVC + Glimmer Web Components (Views) + Data-Binding:
 
 ```ruby
@@ -2060,13 +2680,9 @@ class Counter
   def initialize
     self.count = 0
   end
-
-  def increment!
-    self.count += 1
-  end
 end
 
-class HelloButton
+class ButtonCounter
   include Glimmer::Web::Component
   
   before_render do
@@ -2074,32 +2690,31 @@ class HelloButton
   end
   
   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'
-      
+    div {
       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}  " }]
+        inner_text <= [@counter, :count,
+                        on_read: ->(value) { "Click To Increment: #{value}  " }
+                      ]
         
         onclick {
-          @counter.increment!
+          @counter.count += 1
         }
       }
     }
   }
 end
 
-HelloButton.render
+ButtonCounter.render
 ```
 
 That produces:
 
 ```html
-<div id="application">
-  <button>
+<div data-parent="body" class="element element-1">
+  <button class="element element-2">
     Click To Increment: 0
   </button>
 </div>
@@ -2108,8 +2723,8 @@ That produces:
 When clicked:
 
 ```html
-<div id="application">
-  <button>
+<div data-parent="body" class="element element-1">
+  <button class="element element-2">
     Click To Increment: 1
   </button>
 </div>
@@ -2118,13 +2733,17 @@ When clicked:
 When clicked 7 times:
 
 ```html
-<div id="application">
-  <button>
+<div data-parent="body" class="element element-1">
+  <button class="element element-2">
     Click To Increment: 7
   </button>
 </div>
 ```
 
+Screenshot:
+
+![Button Counter](/images/glimmer-dsl-web-samples-regular-button-counter.gif)
+
 ## Glimmer Supporting Libraries
 
 Here is a list of notable 3rd party gems used by Glimmer DSL for Web: