glimmer-dsl-web 0.0.10 → 0.0.12

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.12 (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,88 @@ 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
+    # Observer is automatically cleaned up if remove method is called on rendered HelloObserver
+    # or its top-level element
+    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 +561,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 +775,304 @@ 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, Paragraph!**
+
+To facilitate building formatted textual paragraphs in Ruby, the Glimmer GUI DSL is advanced enough to behave differently when using HTML formatting elements: `<br>`, `<strong>`, `<em>`, `<br>`, `<i>`, `<sub>`, `<sup>`, `<del>`, `<ins>`, `<small>`, `<mark>`
+
+Instead of returning Ruby objects that are nested as children within their parent, the Glimmer GUI DSL returns `String` objects directly that can be concatenated to or embedded within other `String` objects via interpolation.
+
+This enables writing code like:
+
+`p {"#{strong('Yesterday, ')}Robert suggested adding a new #{em('feature')} to our software product.#{br}}`
+
+That is close to how it is written in HTML, albeit briefer in Ruby:
+
+`<p><strong>Yesterday, </strong>Robert suggested adding a new <em>feature</em> to our software product.<br></p>`
+
+Formatting elements just like regular elements can accept text content as their first argument or as their block return value. So, the code above could equally be written as follows:
+
+`p {"#{strong{'Yesterday, '}}Robert suggested adding a new #{em{'feature'}} to our software product.#{br}}`
+
+This enables seggregating formatting element attributes if desired, as in this example:
+
+`p {"#{strong(class: 'very-string'){'Yesterday, '}}Robert suggested adding a new #{em(class: 'very-emphasized'){'feature'}} to our software product.#{br}}`
+
+Another way of writing the same code is to pass the text content as the first argument, before attributes:
+
+
+`p {"#{strong('Yesterday, ', class: 'very-string')}Robert suggested adding a new #{em('feature', class: 'very-emphasized')} to our software product.#{br}}`
+
+One last bit of info to keep in mind is that `<span>` generally generates a normal element, except when used inside a `<p>`'s content block, in which case it is assumed to be used for formatting, so
+it returns a `String` to enable code like this:
+
+`p {"#{span('Yesterday, ', style: 'text-decoration: underline;')}Robert suggested adding a new #{em('feature', class: 'very-emphasized')} to our software product.#{br}}`
+
+In any case, below is a full example leveraging the Glimmer GUI DSL alternative approach when utilizing formatting elements underneath a paragraph.
+
+Glimmer GUI code:
+
+```ruby
+require 'glimmer-dsl-web'
+
+class HelloParagraph
+  include Glimmer::Web::Component
+  
+  markup {
+    div {
+      h1(class: 'title') {
+        'Flying Cars Become 100% Safe with AI Powered Balance!'
+      }
+      
+      p(class: 'intro') {"
+        In the early 2030's, #{em('flying cars')} became affordable after their prices dropped
+        below #{small(del('$100,000'))}#{ins('$80,000')} as a result of the innovations of #{strong('Travel-X')}. Still, that did not
+        make #{em('flying cars')} any popular due to the extreme difficulty in piloting such flying vehicles for the average
+        person, making it very tough to pass the tests for getting a piloting license given the learning curve.
+      "}
+      
+      p {"
+        That said, #{b('Travel-X')} has recently come up with a new feature for their flagship #{i('flying car')},
+        the Ptero#{sub(1)}#{sup('TM')}, which relies on AI#{sub(2)} to automatically balance the flying cars in mid-air,
+        thus significantly facilitating their piloting by the average consumer.
+      "}
+      
+      p(class: 'conclusion') {"
+        That Ptero#{sup('TM')} will be so stable and well balanced while flying that the consumer will be able to drive
+        as if it is a plain old car, with the only difference being vertical elevation, the control of which will be handled
+        automatically by AI. The Ptero#{sup('TM')} will debut for #{span(style: 'text-decoration: underline dashed;'){'$79,000'}}.
+      "}
+      
+      h2(class: 'legend-title') {
+        mark('Legend:')
+      }
+      
+      p(class: 'legend') {"
+        #{strong("1- Ptero:")} Pterosaur is flying dinosaur species#{br}
+        #{strong("2- AI:")} Artificial Intelligence#{br}
+      "}
+        
+    }
+  }
+end
+
+Document.ready? do
+  HelloParagraph.render
+end
+```
+
+Screenshot:
+
+--
+
+![Hello, Paragraph!](/images/glimmer-dsl-web-samples-hello-hello-paragraph.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:
@@ -705,8 +1082,6 @@ Learn more about the differences between various [Glimmer](https://github.com/An
 ## Table of Contents
 
 - [Glimmer DSL for Web](#-glimmer-dsl-for-opal-alpha-pure-ruby-web-gui)
-  - [Principles](#principles)
-  - [Background](#background)
   - [Prerequisites](#prerequisites)
   - [Setup](#setup)
   - [Usage](#usage)
@@ -717,11 +1092,16 @@ 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, Paragraph!](#hello-paragraph)
       - [Hello, Input (Date/Time)!](#hello-input-datetime)
       - [Button Counter](#button-counter)
+  - [Design Principles](#design-principles)
+  - [Supporting Libraries](#supporting-libraries)
   - [Glimmer Process](#glimmer-process)
   - [Help](#help)
     - [Issues](#issues)
@@ -736,10 +1116,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 +1144,7 @@ rails new glimmer_app_server
 Add the following to `Gemfile`:
 
 ```
-gem 'glimmer-dsl-web', '~> 0.0.10'
+gem 'glimmer-dsl-web', '~> 0.0.12'
 ```
 
 Run:
@@ -817,7 +1195,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 +1208,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 +1216,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 +1243,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 +1254,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 +1274,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 +1360,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.12'
 ```
 
 Run:
@@ -1055,7 +1490,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`.
 
@@ -1398,13 +1833,95 @@ That produces the following under `<body></body>`:
     table tr:nth-child(even) {
       background: #ccc;
     }
-  </style>
-</div>
+  </style>
+</div>
+```
+
+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
+    # Observer is automatically cleaned up if remove method is called on rendered HelloObserver
+    # or its top-level element
+    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, Form!](/images/glimmer-dsl-web-samples-hello-hello-form.gif)
+![Hello, Observer!](/images/glimmer-dsl-web-samples-hello-hello-observer.gif)
 
 #### Hello, Data-Binding!
 
@@ -1721,9 +2238,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 +2452,304 @@ 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, Paragraph!
+
+To facilitate building formatted textual paragraphs in Ruby, the Glimmer GUI DSL is advanced enough to behave differently when using HTML formatting elements: `<br>`, `<strong>`, `<em>`, `<br>`, `<i>`, `<sub>`, `<sup>`, `<del>`, `<ins>`, `<small>`, `<mark>`
+
+Instead of returning Ruby objects that are nested as children within their parent, the Glimmer GUI DSL returns `String` objects directly that can be concatenated to or embedded within other `String` objects via interpolation.
+
+This enables writing code like:
+
+`p {"#{strong('Yesterday, ')}Robert suggested adding a new #{em('feature')} to our software product.#{br}}`
+
+That is close to how it is written in HTML, albeit briefer in Ruby:
+
+`<p><strong>Yesterday, </strong>Robert suggested adding a new <em>feature</em> to our software product.<br></p>`
+
+Formatting elements just like regular elements can accept text content as their first argument or as their block return value. So, the code above could equally be written as follows:
+
+`p {"#{strong{'Yesterday, '}}Robert suggested adding a new #{em{'feature'}} to our software product.#{br}}`
+
+This enables seggregating formatting element attributes if desired, as in this example:
+
+`p {"#{strong(class: 'very-string'){'Yesterday, '}}Robert suggested adding a new #{em(class: 'very-emphasized'){'feature'}} to our software product.#{br}}`
+
+Another way of writing the same code is to pass the text content as the first argument, before attributes:
+
+
+`p {"#{strong('Yesterday, ', class: 'very-string')}Robert suggested adding a new #{em('feature', class: 'very-emphasized')} to our software product.#{br}}`
+
+One last bit of info to keep in mind is that `<span>` generally generates a normal element, except when used inside a `<p>`'s content block, in which case it is assumed to be used for formatting, so
+it returns a `String` to enable code like this:
+
+`p {"#{span('Yesterday, ', style: 'text-decoration: underline;')}Robert suggested adding a new #{em('feature', class: 'very-emphasized')} to our software product.#{br}}`
+
+In any case, below is a full example leveraging the Glimmer GUI DSL alternative approach when utilizing formatting elements underneath a paragraph.
+
+Glimmer GUI code:
+
+```ruby
+require 'glimmer-dsl-web'
+
+class HelloParagraph
+  include Glimmer::Web::Component
+  
+  markup {
+    div {
+      h1(class: 'title') {
+        'Flying Cars Become 100% Safe with AI Powered Balance!'
+      }
+      
+      p(class: 'intro') {"
+        In the early 2030's, #{em('flying cars')} became affordable after their prices dropped
+        below #{small(del('$100,000'))}#{ins('$80,000')} as a result of the innovations of #{strong('Travel-X')}. Still, that did not
+        make #{em('flying cars')} any popular due to the extreme difficulty in piloting such flying vehicles for the average
+        person, making it very tough to pass the tests for getting a piloting license given the learning curve.
+      "}
+      
+      p {"
+        That said, #{b('Travel-X')} has recently come up with a new feature for their flagship #{i('flying car')},
+        the Ptero#{sub(1)}#{sup('TM')}, which relies on AI#{sub(2)} to automatically balance the flying cars in mid-air,
+        thus significantly facilitating their piloting by the average consumer.
+      "}
+      
+      p(class: 'conclusion') {"
+        That Ptero#{sup('TM')} will be so stable and well balanced while flying that the consumer will be able to drive
+        as if it is a plain old car, with the only difference being vertical elevation, the control of which will be handled
+        automatically by AI. The Ptero#{sup('TM')} will debut for #{span(style: 'text-decoration: underline dashed;'){'$79,000'}}.
+      "}
+      
+      h2(class: 'legend-title') {
+        mark('Legend:')
+      }
+      
+      p(class: 'legend') {"
+        #{strong("1- Ptero:")} Pterosaur is flying dinosaur species#{br}
+        #{strong("2- AI:")} Artificial Intelligence#{br}
+      "}
+        
+    }
+  }
+end
+
+Document.ready? do
+  HelloParagraph.render
+end
+```
+
+Screenshot:
+
+--
+
+![Hello, Paragraph!](/images/glimmer-dsl-web-samples-hello-hello-paragraph.png)
+
+--
+
 #### Hello, Input (Date/Time)!
 
 Glimmer GUI code:
@@ -2047,8 +2859,6 @@ Screenshot:
 
 #### Button Counter
 
-**UPCOMING (NOT RELEASED OR SUPPORTED YET)**
-
 Glimmer GUI code demonstrating MVC + Glimmer Web Components (Views) + Data-Binding:
 
 ```ruby
@@ -2060,13 +2870,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 +2880,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 +2913,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,14 +2923,29 @@ 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>
 ```
 
-## Glimmer Supporting Libraries
+Screenshot:
+
+![Button Counter](/images/glimmer-dsl-web-samples-regular-button-counter.gif)
+
+## Design Principles
+
+- The Ruby Way (including TIMTOWTDI: There Is More Than One Way To Do It)
+- The Rails Way Convention over Configuration via smart defaults and automation of low-level details
+- Requiring the least amount of syntax possible to build highly interactive web pages
+- Declarative syntax that visually maps to the DOM (Document Object Model) hierarchy
+- Ability to mix declarative and imperative code conveniently in one language
+- Computers serve Software Engineers (not Software Engineers serve Computers)
+- Think only about real world concepts directly relevant to web page interaction
+- Modular Software Design (e.g. support for Components)
+
+## Supporting Libraries
 
 Here is a list of notable 3rd party gems used by Glimmer DSL for Web:
 - [glimmer-dsl-xml](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML & HTML in pure Ruby.