glimmer-dsl-web 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 968cea935d70d244e06ab3edce32c14c9483ac897e09d9ab5e578cfc0c19ce71
-  data.tar.gz: 138548a00c394758b57a7848f9940748fc3df0dfd19a1638c79e26c5c7325424
+  metadata.gz: 702f2aed3db1d4fcb6fbda9e794a756a3cdb44dfa47db714bbd350a5dd5e1d81
+  data.tar.gz: 5c6b8c276bc246c023cb9419744bceea8021450943cf7e2da2dfb0f86cbb4b3c
 SHA512:
-  metadata.gz: 5cbe3be5841ec5519f8fc23ae620e6b0545dd8c736a865bed49b161fdb2a4f07faecc3dcddec08a6066c64a30c39e1eb3b753ad74e50633a3b505193832151a5
-  data.tar.gz: e2f6709c7356a0d32c3170789bf7f958db98906d7c7dbbfca1dec7483f43865c961e3facb0d3889ffd28fd4818b1e4850b3a8cbdfe231b4352825aacaabfd2ce
+  metadata.gz: 5e3dbff73a4ebb082523dbcf76facc65d27a93e69e2873c08f02bd5939b34a1e9292eadd7698963d5eb53cfa164fbf7b2b14a100213c5d0f3d8d5566d6dc08cd
+  data.tar.gz: dfcc0d083636b8d0943b1ff78215c73651bfe768b970ac9cf81852a9e29ab54bf18f94d49483dc4753154c5497cbeb0f99acfbf91d684eebb97d533be19ccb30

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change Log
 
+## 0.5.0
+
+- Support Glimmer Web Component Slots (by adding `slot: :slot_name` to any parent element, like a `div`, inside a `Glimmer::Web::Component` `markup {...}` element)
+
 ## 0.4.4
 
 - Support setting element `style` property as String or Hash (like `background-color: yello; font-size: 12px;` or `{background_color: :yellow, font_size: 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.4.4 (Beta)
+# [<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.5.0 (Beta)
 ## Ruby-in-the-Browser Web Frontend Framework
 ### Finally, Ruby Developer Productivity, Happiness, and Fun in the Frontend!!!
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-web.svg)](http://badge.fury.io/rb/glimmer-dsl-web)
@@ -12,7 +12,7 @@
 
 You can finally have Ruby developer happiness and productivity in the Frontend! No more wasting time splitting your resources across multiple languages, using badly engineered, over-engineered, or premature-optimization-obsessed JavaScript libraries, fighting JavaScript build issues (e.g. webpack), or rewriting Ruby Backend code in Frontend JavaScript. With [Ruby in the Browser](https://www.youtube.com/watch?v=4AdcfbI6A4c), you can have an exponential jump in development productivity (2x or higher), time-to-release (1/2 or less time), cost (1/2 or cheaper), and maintainability (~50% the code that is simpler and more readable) over JavaScript libraries like React, Angular, Ember, Vue, and Svelte, while being able to reuse Backend Ruby code as is in the Frontend for faster interactions when needed. Also, with Frontend Ruby, companies can cut their hiring budget in half by having Backend Ruby Software Engineers do Frontend Development in Ruby! [Ruby in the Browser](https://www.youtube.com/watch?v=4AdcfbI6A4c) finally fulfills every smart highly-productive Rubyist's dream by bringing Ruby productivity fun to Frontend Development, the same productivity fun you had for years and decades in Backend Development.
 
-[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for Web enables building Web 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 supports Rails' principle of the One Person Framework by not requiring any extra developers with JavaScript expertise, yet enabling Ruby (Backend) Software Engineers to develop the Frontend with Ruby code that is better than any JavaScript code produced by JS developers. It aims at providing the simplest, most intuitive, most straight-forward, and most productive frontend framework in existence. The framework 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)) in building Isomorphic Ruby on Rails Applications. It provides a Ruby [HTML DSL](#usage) (including full support for [SVG](#hello-svg)), which uniquely enables writing both structure code and logic code in one language. It supports 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). Modular design is supported with [Glimmer Web Components](#hello-component). And, a Ruby CSS DSL is supported with the included [Glimmer DSL for CSS](https://github.com/AndyObtiva/glimmer-dsl-css). To automatically convert legacy HTML & CSS code to Glimmer DSL Ruby code, Software Engineers could use the included [`html_to_glimmer`](https://github.com/AndyObtiva/glimmer-dsl-xml#html-to-glimmer-converter) and [`css_to_glimmer`](https://github.com/AndyObtiva/glimmer-dsl-css#css-to-glimmer-converter) commands. Many [samples](#samples) are demonstrated in the [Rails sample app](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app) (there is a very minimal [Standalone [No Rails] static site sample app](https://github.com/Largo/glimmer-dsl-web-standalone-demo) too). 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 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 supports Rails' principle of the One Person Framework by not requiring any extra developers with JavaScript expertise, yet enabling Ruby (Backend) Software Engineers to develop the Frontend with Ruby code that is better than any JavaScript code produced by JS developers. It aims at providing the simplest, most intuitive, most straight-forward, and most productive frontend framework in existence. The framework 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)) in building Isomorphic Ruby on Rails Applications. It provides a Ruby [HTML DSL](#usage) (including full support for [SVG](#hello-svg)), which uniquely enables writing both structure code and logic code in one language. It supports 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). Modular design is supported with [Glimmer Web Components](#hello-component) and [Slots](#hello-component-slots). And, a Ruby CSS DSL is supported with the included [Glimmer DSL for CSS](https://github.com/AndyObtiva/glimmer-dsl-css). To automatically convert legacy HTML & CSS code to Glimmer DSL Ruby code, Software Engineers could use the included [`html_to_glimmer`](https://github.com/AndyObtiva/glimmer-dsl-xml#html-to-glimmer-converter) and [`css_to_glimmer`](https://github.com/AndyObtiva/glimmer-dsl-css#css-to-glimmer-converter) commands. Many [samples](#samples) are demonstrated in the [Rails sample app](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app) (there is a very minimal [Standalone [No Rails] static site sample app](https://github.com/Largo/glimmer-dsl-web-standalone-demo) too). 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 DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) aims to be a very simple Ruby-based drop-in replacement for your existing JavaScript Frontend library (e.g. React, Angular, Vue, Ember, Svelte) or your JavaScript Frontend layer in general. It does not change how your Frontend interacts with the Backend, meaning you can continue to write Rails Backend API endpoints as needed and make HTTP/Ajax requests or read data embedded in elements, but from [Ruby in the Browser](https://www.youtube.com/watch?v=4AdcfbI6A4c). Whatever is possible in JavaScript is possible when using Glimmer DSL for Web as it integrates with any existing JavaScript library. The [Rails sample app](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app) demonstrates how to [make HTTP calls](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/blob/master/app/assets/opal/sample_selector/models/sample_api.rb) and how to [integrate with a JavaScript library](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/blob/master/app/views/layouts/application.html.erb) (highlightjs) that performs [code syntax highlighting](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/blob/master/app/assets/opal/sample_selector.rb).
 
@@ -578,6 +578,15 @@ Rails helper (more about it in [Hello, glimmer_component Rails Helper!](#hello-g
 Below, we define an `AddressForm` component that generates an `address_form` keyword, and then we
 reuse it twice inside an `AddressPage` component displaying a Shipping Address and a Billing Address.
 
+You can specify CSS styles that apply to all instances of a component by opening a `style {...}` block, which is
+evaluated against the component class given that it applies to all instances.
+That would automatically generate one `<style>` element for a component inside `<head>` if at least one instance
+of it exists. Every Glimmer web component's markup root element will automatically get a CSS class matching its Ruby
+class name underscored, which can be used to scope styles for all component instances inside its `style {...}` block.
+For example, `AddressForm` gets the CSS class `address-form` on its top-level `div`. You can find out the default CSS class
+that is attached to every component by calling `ComponentClass.component_element_class`. You can get a CSS selector version of
+it by calling `ComponentClass.component_element_selector`.
+
 [lib/glimmer-dsl-web/samples/hello/hello_component.rb](/lib/glimmer-dsl-web/samples/hello/hello_component.rb)
 
 Glimmer HTML DSL Ruby code in the frontend:
@@ -1333,7 +1342,8 @@ Learn more about the differences between various [Glimmer](https://github.com/An
       - [Hello, Observer (Data-Binding)!](#hello-observer)
       - [Hello, Data-Binding!](#hello-data-binding)
       - [Hello, Content Data-Binding!](#hello-content-data-binding)
-      - [Hello, Component!](#hello-content-data-binding)
+      - [Hello, Component!](#hello-compoent)
+      - [Hello, Component Slots!](#hello-component-slots)
       - [Hello, glimmer_component Rails Helper!](#hello-glimmer_component-rails-helper)
       - [Hello, Paragraph!](#hello-paragraph)
       - [Hello, Style!](#hello-style)
@@ -1390,7 +1400,7 @@ rails new glimmer_app_server
 Add the following to `Gemfile`:
 
 ```
-gem 'glimmer-dsl-web', '~> 0.4.4'
+gem 'glimmer-dsl-web', '~> 0.5.0'
 ```
 
 Run:
@@ -1619,7 +1629,7 @@ Disable the `webpacker` gem line in `Gemfile`:
 Add the following to `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-web', '~> 0.4.4'
+gem 'glimmer-dsl-web', '~> 0.5.0'
 ```
 
 Run:
@@ -2630,6 +2640,15 @@ Rails helper (more about it in [Hello, glimmer_component Rails Helper!](#hello-g
 Below, we define an `AddressForm` component that generates an `address_form` keyword, and then we
 reuse it twice inside an `AddressPage` component displaying a Shipping Address and a Billing Address.
 
+You can specify CSS styles that apply to all instances of a component by opening a `style {...}` block, which is
+evaluated against the component class given that it applies to all instances.
+That would automatically generate one `<style>` element for a component inside `<head>` if at least one instance
+of it exists. Every Glimmer web component's markup root element will automatically get a CSS class matching its Ruby
+class name underscored, which can be used to scope styles for all component instances inside its `style {...}` block.
+For example, `AddressForm` gets the CSS class `address-form` on its top-level `div`. You can find out the default CSS class
+that is attached to every component by calling `ComponentClass.component_element_class`. You can get a CSS selector version of
+it by calling `ComponentClass.component_element_selector`.
+
 [lib/glimmer-dsl-web/samples/hello/hello_component.rb](/lib/glimmer-dsl-web/samples/hello/hello_component.rb)
 
 Glimmer HTML DSL Ruby code in the frontend:
@@ -2841,6 +2860,233 @@ Screenshot:
 
 ![Hello, Component!](/images/glimmer-dsl-web-samples-hello-hello-component.png)
 
+#### Hello, Component Slots!
+
+Component slots enables consumers of components to contribute content in designated areas inside them called slots.
+
+Inside a Glimmer web component, you can designate an element (e.g. `div`) as a component slot by passing the `slot: :slotname` option,
+which enables consumers to contribute elements inside the component slot by opening a `slotname {...}` inside the component content block.
+
+For example, below is a sample that demonstrates how to contribute slot content to `address_header` and `address_footer` in an `address_form` component.
+
+[lib/glimmer-dsl-web/samples/hello/hello_component_slots.rb](/lib/glimmer-dsl-web/samples/hello/hello_component_slots.rb)
+
+Glimmer HTML DSL Ruby code in the frontend:
+
+```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 HTML 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 HTML DSL code as done inside HelloComponentSlots below.
+class AddressForm
+  include Glimmer::Web::Component
+  
+  option :address
+  
+  # markup block provides the content of the
+  markup {
+    div {
+      # designate this div as a slot with the slot name :address_header to enable
+      # consumers to contribute elements to `address_header {...}` slot
+      div(slot: :address_header, class: 'address-form-header')
+      
+      div(class: 'address-field-container', style: {display: :grid, grid_auto_columns: '80px 260px'}) {
+        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,
+                    ]
+        }
+      }
+      
+      div(style: 'margin: 5px') {
+        inner_text <= [address, :summary,
+                        computed_by: address.members + ['state_code'],
+                      ]
+      }
+      
+      # designate this div as a slot with the slot name :address_footer to enable
+      # consumers to contribute elements to `address_footer {...}` slot
+      div(slot: :address_footer, class: 'address-form-footer')
+    }
+  }
+  
+  style {
+    r('.address-field-container *') {
+      margin 5
+    }
+    r('.address-field-container input, .address-field-container select') {
+      grid_column '2'
+    }
+  }
+end
+
+# HelloComponentSlots Glimmer Web Component (View component)
+#
+# This View component represents the main page being rendered,
+# as done by its `render` class method below
+class HelloComponentSlots
+  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 {
+      address_form(address: @shipping_address) {
+        address_header { # contribute elements to the address_header component slot
+          h1('Shipping Address')
+          legend('This is the address that is used for shipping your purchase.', style: {margin_bottom: 10})
+        }
+        address_footer { # contribute elements to the address_header component slot
+          p(sub("#{strong('Note:')} #{em('Purchase will be returned if the Shipping Address does not accept it in one week.')}"))
+        }
+      }
+      
+      address_form(address: @billing_address) {
+        address_header { # contribute elements to the address_header component slot
+          h1('Billing Address')
+          legend('This is the address that is used for your billing method (e.g. credit card).', style: {margin_bottom: 10})
+        }
+        address_footer { # contribute elements to the address_header component slot
+          p(sub("#{strong('Note:')} #{em('Payment will fail if payment method does not match the Billing Address.')}"))
+        }
+      }
+    }
+  }
+end
+
+Document.ready? do
+  # renders a top-level (root) HelloComponentSlots component
+  HelloComponentSlots.render
+end
+```
+
+Screenshot:
+
+![Hello, Component Slots!](/images/glimmer-dsl-web-samples-hello-hello-component-slots.png)
+
 #### Hello, glimmer_component Rails Helper!
 
 You may insert a Glimmer component anywhere into a Rails View using

data/VERSION

@@ -1 +1 @@
-0.4.4
+0.5.0

data/glimmer-dsl-web.gemspec

@@ -2,17 +2,17 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: glimmer-dsl-web 0.4.4 ruby lib
+# stub: glimmer-dsl-web 0.5.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "glimmer-dsl-web".freeze
-  s.version = "0.4.4"
+  s.version = "0.5.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Andy Maleh".freeze]
   s.date = "2024-08-03"
-  s.description = "Glimmer DSL for Web (Ruby in the Browser Web Frontend Framework) enables building Web Frontends using Ruby in the Browser, as per Matz's recommendation in his RubyConf 2022 keynote speech to replace JavaScript with Ruby. It aims at providing the simplest, most intuitive, most straight-forward, and most productive frontend framework in existence. The framework follows the Ruby way (with DSLs and TIMTOWTDI) and the Rails way (Convention over Configuration) in building Isomorphic Ruby on Rails Applications. It provides a Ruby HTML DSL, which uniquely enables writing both structure code and logic code in one language. It supports both Unidirectional (One-Way) Data-Binding (using <=) and Bidirectional (Two-Way) Data-Binding (using <=>). Dynamic rendering (and re-rendering) of HTML content is also supported via Content Data-Binding. Modular design is supported with Glimmer Web Components. And, a Ruby CSS DSL is supported with the included Glimmer DSL for CSS. Many samples are demonstrated in the Rails sample app (there is a very minimal Standalone [No Rails] sample app too). You can finally live in pure Rubyland on the Web in both the frontend and backend with Glimmer DSL for Web! This gem relies on Opal Ruby.".freeze
+  s.description = "Glimmer DSL for Web (Ruby in the Browser Web Frontend Framework) enables building Web Frontends using Ruby in the Browser, as per Matz's recommendation in his RubyConf 2022 keynote speech to replace JavaScript with Ruby. It aims at providing the simplest, most intuitive, most straight-forward, and most productive frontend framework in existence. The framework follows the Ruby way (with DSLs and TIMTOWTDI) and the Rails way (Convention over Configuration) in building Isomorphic Ruby on Rails Applications. It provides a Ruby HTML DSL, which uniquely enables writing both structure code and logic code in one language. It supports both Unidirectional (One-Way) Data-Binding (using <=) and Bidirectional (Two-Way) Data-Binding (using <=>). Dynamic rendering (and re-rendering) of HTML content is also supported via Content Data-Binding. Modular design is supported with Glimmer Web Components and Slots. And, a Ruby CSS DSL is supported with the included Glimmer DSL for CSS. Many samples are demonstrated in the Rails sample app (there is a very minimal Standalone [No Rails] sample app too). You can finally live in pure Rubyland on the Web in both the frontend and backend with Glimmer DSL for Web! This gem relies on Opal Ruby.".freeze
   s.email = "andy.am@gmail.com".freeze
   s.extra_rdoc_files = [
     "CHANGELOG.md",
@@ -33,6 +33,7 @@ Gem::Specification.new do |s|
     "lib/glimmer-dsl-web/ext/kernel.rb",
     "lib/glimmer-dsl-web/samples/hello/hello_button.rb",
     "lib/glimmer-dsl-web/samples/hello/hello_component.rb",
+    "lib/glimmer-dsl-web/samples/hello/hello_component_slots.rb",
     "lib/glimmer-dsl-web/samples/hello/hello_content_data_binding.rb",
     "lib/glimmer-dsl-web/samples/hello/hello_data_binding.rb",
     "lib/glimmer-dsl-web/samples/hello/hello_form.rb",
@@ -68,6 +69,7 @@ Gem::Specification.new do |s|
     "lib/glimmer/dsl/web/bind_expression.rb",
     "lib/glimmer/dsl/web/class_name_inclusion_data_binding.rb",
     "lib/glimmer/dsl/web/component_expression.rb",
+    "lib/glimmer/dsl/web/component_slot_content_expression.rb",
     "lib/glimmer/dsl/web/content_data_binding_expression.rb",
     "lib/glimmer/dsl/web/data_binding_expression.rb",
     "lib/glimmer/dsl/web/dsl.rb",

data/lib/glimmer/dsl/web/component_slot_content_expression.rb

@@ -0,0 +1,48 @@
+# Copyright (c) 2023-2024 Andy Maleh
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'glimmer'
+require 'glimmer/dsl/expression'
+require 'glimmer/web/component'
+
+module Glimmer
+  module DSL
+    module Web
+      class ComponentSlotContentExpression < Expression
+        def can_interpret?(parent, keyword, *args, &block)
+          slot = keyword.to_s
+          block_given? &&
+            parent.respond_to?(:slot_elements) &&
+            (
+              parent.slot_elements.keys.include?(slot) ||
+              parent.slot_elements.keys.include?(slot.to_sym)
+            )
+        end
+  
+        def interpret(parent, keyword, *args, &block)
+          slot = keyword.to_s
+          slot_element = parent.slot_elements[slot] || parent.slot_elements[slot.to_sym]
+          slot_element&.content(&block)
+        end
+      end
+    end
+  end
+end

data/lib/glimmer/dsl/web/dsl.rb

@@ -34,6 +34,7 @@ require 'glimmer/dsl/web/data_binding_expression'
 require 'glimmer/dsl/web/content_data_binding_expression'
 require 'glimmer/dsl/web/shine_data_binding_expression'
 require 'glimmer/dsl/web/component_expression'
+require 'glimmer/dsl/web/component_slot_content_expression'
 require 'glimmer/dsl/web/observe_expression'
 
 module Glimmer
@@ -47,6 +48,7 @@ module Glimmer
          content_data_binding
          inline_style_data_binding
          class_name_inclusion_data_binding
+         component_slot_content
          component
          formatting_element
          data_binding

data/lib/glimmer/dsl/web/element_expression.rb

@@ -10,9 +10,17 @@ module Glimmer
         include GeneralElementExpression
         
         def can_interpret?(parent, keyword, *args, &block)
+          slot = keyword.to_s.to_sym
           Glimmer::Web::ElementProxy.keyword_supported?(keyword) &&
             (
-              args.empty? ||
+              (
+                args.empty? &&
+                (
+                  parent.nil? ||
+                  !parent.respond_to?(:slot_elements) ||
+                  !(parent.slot_elements.keys.include?(slot) || parent.slot_elements.keys.include?(slot.to_s))
+                )
+              ) ||
               args.size == 1 && args.first.is_a?(String) ||
               args.size == 1 && args.first.is_a?(Hash) ||
               args.size == 2 && args.first.is_a?(String) && args.last.is_a?(Hash)

data/lib/glimmer/web/component.rb

@@ -255,7 +255,7 @@ module Glimmer
       end
       # <- end of class methods
       
-      attr_reader :markup_root, :parent, :args, :options, :style_block, :component_style
+      attr_reader :markup_root, :parent, :args, :options, :style_block, :component_style, :slot_elements
       alias parent_proxy parent
 
       def initialize(parent, args, options, &content)
@@ -268,6 +268,7 @@ module Glimmer
           args = []
         end
         options ||= {}
+        @slot_elements = {}
         @args = args
         options ||= {}
         @options = self.class.options.merge(options)

data/lib/glimmer/web/element_proxy.rb

@@ -146,17 +146,22 @@ module Glimmer
       REGEX_STYLE_SUB_PROPERTY = /^(style)_(.*)$/
       REGEX_CLASS_NAME_SUB_PROPERTY = /^(class_name)_(.*)$/
       
-      attr_reader :keyword, :parent, :parent_component, :component, :args, :options, :children, :enabled, :foreground, :background, :removed, :rendered
+      attr_reader :keyword, :parent, :parent_component, :ancestor_component, :component, :args, :options, :slot, :children, :enabled, :foreground, :background, :removed, :rendered
       alias rendered? rendered
       alias removed? removed
       
       def initialize(keyword, parent, args, block)
         @keyword = keyword
         @parent = parent.is_a?(Glimmer::Web::Component) ? parent.markup_root : parent
+        # @parent_component is the component that is the parent of an external element (not in markup {...} block) that is nested underneath (e.g. address_form { this_element })
         @parent_component = parent if parent.is_a?(Glimmer::Web::Component)
         if Component.interpretation_stack.last&.markup_root.nil?
+          # @component is the one tied to this component-internal element as the markup root
           @component = Component.interpretation_stack.last
           @component&.instance_variable_set("@markup_root", self)
+        else
+          # @ancestor_component is the one tied to this component-internal element as an ancestor
+          @ancestor_component = Component.interpretation_stack.last
         end
         @options = args.last.is_a?(Hash) ? args.last.symbolize_keys : {}
         if parent.nil?
@@ -164,6 +169,9 @@ module Glimmer
           options[:render] ||= Component.interpretation_stack.last&.options&.[](:render)
           options[:bulk_render] ||= Component.interpretation_stack.last&.options&.[](:bulk_render)
         end
+        @slot = options['slot'] || options[:slot]
+        @slot = @slot.to_sym if @slot
+        ancestor_component.slot_elements[@slot] = self if @slot && ancestor_component
         @args = args
         @block = block
         @children = []
@@ -171,6 +179,10 @@ module Glimmer
         render if !bulk_render? && !@rendered && render_after_create?
       end
       
+      def ancestor_component
+        @ancestor_component || @component
+      end
+      
       def bulk_render?
         options[:bulk_render] != false && (@parent.nil? || @parent.bulk_render?)
       end

data/lib/glimmer-dsl-web/samples/hello/hello_component_slots.rb

@@ -0,0 +1,228 @@
+# Copyright (c) 2023-2024 Andy Maleh
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+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 HTML 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 HTML DSL code as done inside HelloComponentSlots below.
+class AddressForm
+  include Glimmer::Web::Component
+  
+  option :address
+  
+  # markup block provides the content of the
+  markup {
+    div {
+      # designate this div as a slot with the slot name :address_header to enable
+      # consumers to contribute elements to `address_header {...}` slot
+      div(slot: :address_header, class: 'address-form-header')
+      
+      div(class: 'address-field-container', style: {display: :grid, grid_auto_columns: '80px 260px'}) {
+        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,
+                    ]
+        }
+      }
+      
+      div(style: 'margin: 5px') {
+        inner_text <= [address, :summary,
+                        computed_by: address.members + ['state_code'],
+                      ]
+      }
+      
+      # designate this div as a slot with the slot name :address_footer to enable
+      # consumers to contribute elements to `address_footer {...}` slot
+      div(slot: :address_footer, class: 'address-form-footer')
+    }
+  }
+  
+  style {
+    r('.address-field-container *') {
+      margin 5
+    }
+    r('.address-field-container input, .address-field-container select') {
+      grid_column '2'
+    }
+  }
+end
+
+# HelloComponentSlots Glimmer Web Component (View component)
+#
+# This View component represents the main page being rendered,
+# as done by its `render` class method below
+class HelloComponentSlots
+  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 {
+      address_form(address: @shipping_address) {
+        address_header { # contribute elements to the address_header component slot
+          h1('Shipping Address')
+          legend('This is the address that is used for shipping your purchase.', style: {margin_bottom: 10})
+        }
+        address_footer { # contribute elements to the address_header component slot
+          p(sub("#{strong('Note:')} #{em('Purchase will be returned if the Shipping Address does not accept it in one week.')}"))
+        }
+      }
+      
+      address_form(address: @billing_address) {
+        address_header { # contribute elements to the address_header component slot
+          h1('Billing Address')
+          legend('This is the address that is used for your billing method (e.g. credit card).', style: {margin_bottom: 10})
+        }
+        address_footer { # contribute elements to the address_header component slot
+          p(sub("#{strong('Note:')} #{em('Payment will fail if payment method does not match the Billing Address.')}"))
+        }
+      }
+    }
+  }
+end
+
+Document.ready? do
+  # renders a top-level (root) HelloComponentSlots component
+  HelloComponentSlots.render
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glimmer-dsl-web
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.5.0
 platform: ruby
 authors:
 - Andy Maleh
@@ -240,11 +240,12 @@ description: Glimmer DSL for Web (Ruby in the Browser Web Frontend Framework) en
   both structure code and logic code in one language. It supports both Unidirectional
   (One-Way) Data-Binding (using <=) and Bidirectional (Two-Way) Data-Binding (using
   <=>). Dynamic rendering (and re-rendering) of HTML content is also supported via
-  Content Data-Binding. Modular design is supported with Glimmer Web Components. And,
-  a Ruby CSS DSL is supported with the included Glimmer DSL for CSS. Many samples
-  are demonstrated in the Rails sample app (there is a very minimal Standalone [No
-  Rails] sample app too). You can finally live in pure Rubyland on the Web in both
-  the frontend and backend with Glimmer DSL for Web! This gem relies on Opal Ruby.
+  Content Data-Binding. Modular design is supported with Glimmer Web Components and
+  Slots. And, a Ruby CSS DSL is supported with the included Glimmer DSL for CSS. Many
+  samples are demonstrated in the Rails sample app (there is a very minimal Standalone
+  [No Rails] sample app too). You can finally live in pure Rubyland on the Web in
+  both the frontend and backend with Glimmer DSL for Web! This gem relies on Opal
+  Ruby.
 email: andy.am@gmail.com
 executables: []
 extensions: []
@@ -266,6 +267,7 @@ files:
 - lib/glimmer-dsl-web/ext/kernel.rb
 - lib/glimmer-dsl-web/samples/hello/hello_button.rb
 - lib/glimmer-dsl-web/samples/hello/hello_component.rb
+- lib/glimmer-dsl-web/samples/hello/hello_component_slots.rb
 - lib/glimmer-dsl-web/samples/hello/hello_content_data_binding.rb
 - lib/glimmer-dsl-web/samples/hello/hello_data_binding.rb
 - lib/glimmer-dsl-web/samples/hello/hello_form.rb
@@ -301,6 +303,7 @@ files:
 - lib/glimmer/dsl/web/bind_expression.rb
 - lib/glimmer/dsl/web/class_name_inclusion_data_binding.rb
 - lib/glimmer/dsl/web/component_expression.rb
+- lib/glimmer/dsl/web/component_slot_content_expression.rb
 - lib/glimmer/dsl/web/content_data_binding_expression.rb
 - lib/glimmer/dsl/web/data_binding_expression.rb
 - lib/glimmer/dsl/web/dsl.rb