glimmer-dsl-web 0.10.3 → 0.10.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9612f4c1844bb9ccf62e32d1682a71bb933268fc9e9a74837a89a558001b96b0
-  data.tar.gz: c6bffc8d775f74c96f13cad87702648f2da115fd7da7de998946a7dc33572410
+  metadata.gz: 64fc435ce1a727a890882f43c0851f932f699a610fbfea88041e0606f1fac8b7
+  data.tar.gz: da253a9bccb769f519c20f53810410360cd45034722fbe5083f2847c8e5f3080
 SHA512:
-  metadata.gz: 5747a2f6092a03c2c0ae35c666f615aca23eac99b6b98eed533bf2876e747ca97bb33bd6a2f89285f34dcd0520873c2538e85306149cfbe5184fb921e4128928
-  data.tar.gz: 381d39d680af48941b8282aa180e4f6cd6641f7c79e408739c4e2e4838507f7e084011408f59dc09c5183c39912ec8b1cf6abbdadcff0f0587ec6d9151104d82
+  metadata.gz: f67ac1fc2adadfd190106296d70fec7aa267368a7d33660836dde5198f9e4ad05942674707758ae10293c9c2213ad7031fd0f9ab9fc8a0ca75dd7cb8f1a75fa4
+  data.tar.gz: aa2115656cc49ec3eafe7f2717051dd6fda8bec038906fcbc574d25265a094231b7409ecd2c49ada131515365729f2bf6fc0331bc5cbe68e07b69cb35967307c

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## 0.10.4
+
+- Support `parent.insert_at(index) {}` on `ElementProxy` and `Glimmer::Web::Component`, which is a method that inserts elements to the content of a parent element at a specified index
+- Support `parent.insert(index) {}` alias for `parent.insert_at(index) {}`
+- Update Hello, Mutation! sample with "Insert list item" functionality
+- Update Hello, Mutation Content Data-Binding! sample with "Insert list item" functionality
+- Document DOM mutation operations in README
+
 ## 0.10.3
 
 - Support `parent.prepend {}` on `ElementProxy` and `Glimmer::Web::Component`, which is a method that prepends elements to the content of a parent element

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.10.3 (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.10.4 (Beta)
 ## Ruby-in-the-Browser Web Frontend Framework
 ### The "Rails" of Frontend Frameworks!!! ([Fukuoka Award Winning](https://andymaleh.blogspot.com/2025/01/glimmer-dsl-for-web-wins-in-fukuoka.html))
 #### Finally, Ruby Developer Productivity, Happiness, and Fun in the Frontend!!!
@@ -1498,6 +1498,52 @@ p(class: 'summary') {
 
 You can get/set any element property or invoke any element function by simply calling the lowercase underscored version of their name in Ruby like `input.check_validity`, `input.value`, and `input.id`.
 
+Additionally, these DOM mutation operations are available as methods on elements/components acting as parents:
+- `parent.append { }` : apprends elements inside the content of the parent
+- `parent.prepend { }` : prepends elements inside the content of the parent
+- `parent.insert_at(index) { }` : inserts elements inside the content of the parent (`insert` is an alias for `insert_at`)
+
+Example:
+
+```ruby
+div {
+  div(class: 'actions') {
+    @input = input(placeholder: 'Enter list item content')
+    
+    @append_button = button('Append list item') {
+      onclick do
+        @list.append { # DOM mutation operation
+          li { @input.value }
+        }
+        @input.value = ''
+        @input.focus
+      end
+    }
+  }
+  
+  @list = ul
+}
+```
+
+Specifically, this line:
+
+```ruby
+@list.append {
+  li { @input.value }
+}
+```
+
+You can append multiple elements too. Here is a different hypothetical example:
+
+```ruby
+@some_div.append {
+  h1 { @post.title }
+  p { @post.content }
+}
+```
+
+DOM mutation operations are useful for adding elements after the fact of initial rendering of the page as triggered by a user action or some system timer.
+
 Next, check out [Samples](#samples).
 
 Note that for serious app usage, it is recommended to build [components](#hello-component) and use the [`glimmer_component` Rails Helper](#hello-glimmer_component-rails-helper) to embed the top-level Web Frontend component in a Rails View.

data/VERSION

@@ -1 +1 @@
-0.10.3
+0.10.4

data/glimmer-dsl-web.gemspec

@@ -2,11 +2,11 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: glimmer-dsl-web 0.10.3 ruby lib
+# stub: glimmer-dsl-web 0.10.4 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "glimmer-dsl-web".freeze
-  s.version = "0.10.3".freeze
+  s.version = "0.10.4".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -119,7 +119,7 @@ Gem::Specification.new do |s|
 
   s.specification_version = 4
 
-  s.add_runtime_dependency(%q<glimmer>.freeze, ["~> 2.8.2".freeze])
+  s.add_runtime_dependency(%q<glimmer>.freeze, ["~> 2.8.3".freeze])
   s.add_runtime_dependency(%q<glimmer-dsl-xml>.freeze, ["~> 1.4.0".freeze])
   s.add_runtime_dependency(%q<glimmer-dsl-css>.freeze, ["~> 1.5.2".freeze])
   s.add_runtime_dependency(%q<opal>.freeze, [">= 1.8.2".freeze, "< 2.0.0".freeze])

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

@@ -14,7 +14,9 @@ module Glimmer
         def add_content(parent, keyword, *args, &block)
           options = args.last.is_a?(Hash) ? args.last : {}
           parent_original_add_child_mutation = parent&.add_child_mutation
+          parent_original_insert_index = parent&.insert_index
           parent&.add_child_mutation = options[:add_child_mutation] if options[:add_child_mutation]
+          parent&.insert_index = options[:insert_index] if options[:insert_index]
           if parent.bulk_render? || parent.rendered? || parent.skip_content_on_render_blocks?
             return_value = super(parent, keyword, *args, &block)
             parent.add_text_content(return_value, on_empty: true) if return_value.is_a?(String)
@@ -25,6 +27,7 @@ module Glimmer
           end
         ensure
           parent&.add_child_mutation = parent_original_add_child_mutation
+          parent&.insert_index = parent_original_insert_index
         end
       end
     end

data/lib/glimmer/web/component.rb

@@ -516,6 +516,11 @@ module Glimmer
         @markup_root.prepend(bulk_render:, &block)
       end
       
+      def insert_at(index, bulk_render: false, &block)
+        @markup_root.insert_at(index, bulk_render:, &block)
+      end
+      alias insert insert_at
+      
       def remove_all_listeners
         data_bindings.each do |option_binding, model_binding|
           option_binding.unregister_all_observables

data/lib/glimmer/web/element_proxy.rb

@@ -176,6 +176,7 @@ module Glimmer
       REGEX_CLASS_NAME_SUB_PROPERTY = /^(class_name)_(.*)$/
       
       attr_reader :keyword, :parent, :parent_component, :ancestor_component, :component, :args, :options, :slot, :children, :enabled, :foreground, :background, :removed, :rendered
+      attr_accessor :insert_index # to be used when add_child_mutation is insert_at
       alias rendered? rendered
       alias removed? removed
       
@@ -223,7 +224,14 @@ module Glimmer
       
       # Executes for the parent of a child that just got added
       def post_initialize_child(child)
-        @children << child
+        case parent&.add_child_mutation
+        when :prepend
+          @children.prepend(child)
+        when :insert_at
+          @children.insert(parent&.insert_index, child)
+        else # append
+          @children << child
+        end
         child.render if !bulk_render? && !render_after_create?
       end
       
@@ -445,7 +453,7 @@ module Glimmer
         brand_new ||= @dom.nil? || !options[:parent].to_s.empty? || (old_element = dom_element).empty?
         build_dom(layout: !custom_parent_dom_element) # TODO handle custom parent layout by passing parent instead of parent dom element
         if brand_new
-          attach(the_parent_dom_element, add_child_mutation: self.parent&.add_child_mutation || :append)
+          attach(the_parent_dom_element, add_child_mutation: self.parent&.add_child_mutation, insert_index: self.parent&.insert_index)
         else
           reattach(old_element)
         end
@@ -458,10 +466,17 @@ module Glimmer
       end
       alias rerender render
         
-      def attach(the_parent_dom_element, add_child_mutation: :append)
-        if add_child_mutation == :prepend
+      def attach(the_parent_dom_element, add_child_mutation: :append, insert_index: nil)
+        case add_child_mutation
+        when :prepend
           the_parent_dom_element.prepend(@dom)
-        else
+        when :insert_at
+          if insert_index == the_parent_dom_element.children.size
+            the_parent_dom_element.append(@dom)
+          else
+            the_parent_dom_element.children.eq(insert_index).before(@dom)
+          end
+        else # append
           the_parent_dom_element.append(@dom)
         end
       end
@@ -568,10 +583,10 @@ module Glimmer
         @add_child_mutation = value
       end
       
-      def content(bulk_render: false, add_child_mutation: :append, &block)
+      def content(bulk_render: false, add_child_mutation: :append, insert_index: nil, &block)
         original_bulk_render = options[:bulk_render]
         options[:bulk_render] = bulk_render if rendered?
-        return_value = Glimmer::DSL::Engine.add_content(self, Glimmer::DSL::Web::ElementExpression.new, keyword, add_child_mutation:, &block)
+        return_value = Glimmer::DSL::Engine.add_content(self, Glimmer::DSL::Web::ElementExpression.new, keyword, add_child_mutation:, insert_index:, &block)
         options[:bulk_render] = original_bulk_render if rendered?
         return_value
       end
@@ -581,6 +596,12 @@ module Glimmer
         content(bulk_render:, add_child_mutation: :prepend, &block)
       end
       
+      def insert_at(index, bulk_render: false, &block)
+        index = index.to_i if index.is_a?(String) && index.match(/^\d+$/)
+        content(bulk_render:, add_child_mutation: :insert_at, insert_index: index, &block)
+      end
+      alias insert insert_at
+      
       # Subclasses must override with their own mappings
       def observation_request_to_event_mapping
         {}

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

@@ -1,49 +1,93 @@
 require 'glimmer-dsl-web'
 
-class HelloMutation
-  include Glimmer::Web::Component
-  
-  markup {
-    div {
-      h1('Hello, Mutation!')
-      
-      p {
-        'Add items to a list via element DOM mutations.'
-      }
-      
-      div(class: 'actions') {
-        @input = input(placeholder: 'Enter list item content')
+unless Object.const_defined?(:HelloMutation) # this is only needed in sample selector app due to file reloading, but not in real apps.
+  class HelloMutation
+    include Glimmer::Web::Component
+    
+    after_render do
+      @append_button.disabled = @prepend_button.disabled = @insert_button.disabled = true
+    end
+    
+    markup {
+      div {
+        h1('Hello, Mutation!')
         
-        button('Append list item') {
-          onclick do
-            @list.append {
-              li { @input.value }
-            }
-            @input.value = ''
-            @input.focus
-          end
+        p {
+          'Add items to a list via element DOM mutations.'
         }
         
-        button('Prepend list item') {
-          onclick do
-            @list.prepend {
-              li { @input.value }
-            }
-            @input.value = ''
-            @input.focus
-          end
+        div(class: 'actions') {
+          @input = input(placeholder: 'Enter list item content') {
+            oninput do
+              if @input.value.to_s.strip == ''
+                @append_button.disabled = @prepend_button.disabled = @insert_button.disabled = true
+              else
+                @append_button.disabled = @prepend_button.disabled = @insert_button.disabled = false
+              end
+            end
+          }
+          
+          @append_button = button('Append list item') {
+            onclick do
+              @list.append {
+                li { @input.value }
+              }
+              @append_button.disabled = @prepend_button.disabled = @insert_button.disabled = true
+              @input.value = ''
+              @input.focus
+            end
+          }
+          
+          @prepend_button = button('Prepend list item') {
+            onclick do
+              @list.prepend {
+                li { @input.value }
+              }
+              @append_button.disabled = @prepend_button.disabled = @insert_button.disabled = true
+              @input.value = ''
+              @input.focus
+            end
+          }
+          
+          @insert_button = button('Insert list item') {
+            onclick do
+              index = [@insert_index_input.value.to_i, @list.children.size].min
+              @list.insert_at(index) {
+                li { @input.value }
+              }
+              @append_button.disabled = @prepend_button.disabled = @insert_button.disabled = true
+              @input.value = ''
+              @input.focus
+            end
+          }
+          
+          label(for: 'insert-index-input') { 'at index: ' }
+          @insert_index_input = input(id: 'insert-index-input', type: 'number', value: 0, min: 0) {
+            oninput do
+              max_value = @list.children.size
+              @insert_index_input.value = max_value if @insert_index_input.value.to_i > max_value
+            end
+          }
         }
+        
+        @list = ul
       }
-      
-      @list = ul
     }
-  }
-  
-  style {
-    r('.actions input, .actions button') {
-      margin '10px 10px 10px 0'
+    
+    style {
+      r('.actions input, .actions button') {
+        margin '10px 10px 10px 0'
+      }
+      
+      r('.actions input#insert-index-input') {
+        width 40
+      }
+      
+      r('.actions label[for=insert-index-input]') {
+        margin_left -5
+      }
     }
-  }
+  end
 end
 
 Document.ready? do

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

@@ -1,81 +1,123 @@
 require 'glimmer-dsl-web'
 
-class ListPresenter
-  attr_accessor :list, :new_list_item
-  
-  def initialize
-    @list = []
-    @new_list_item = ''
-  end
-  
-  def append_list_item
-    list.push(new_list_item)
-    clear_new_list_item
-  end
-  
-  def prepend_list_item
-    list.prepend(new_list_item)
-    clear_new_list_item
-  end
-  
-  def clear_new_list_item
-    self.new_list_item = ''
-  end
-  
-  def entering_new_list_item?
-    new_list_item.empty?
+unless Object.const_defined?(:ListPresenter) # this is only needed in sample selector app due to file reloading, but not in real apps.
+  class ListPresenter
+    attr_accessor :list, :new_list_item, :insert_index
+    
+    def initialize
+      @list = []
+      @new_list_item = ''
+      @insert_index = 0
+    end
+    
+    def append_list_item
+      list.push(new_list_item)
+      clear_new_list_item
+    end
+    
+    def prepend_list_item
+      list.prepend(new_list_item)
+      clear_new_list_item
+    end
+    
+    def insert_list_item
+      list.insert(insert_index, new_list_item)
+      clear_new_list_item
+    end
+    
+    def clear_new_list_item
+      self.new_list_item = ''
+    end
+    
+    def entering_new_list_item?
+      new_list_item.empty?
+    end
+    alias edit_list_disabled? entering_new_list_item?
+    
+    def max_insert_index
+      list.size
+    end
   end
 end
 
-class HelloMutationContentDataBinding
-  include Glimmer::Web::Component
-  
-  before_render do
-    @list_presenter = ListPresenter.new
-  end
-  
-  markup {
-    div {
-      h1('Hello, Mutation Content Data-Binding!')
-      
-      p {
-        'Add items to a list via content data-binding (which performs implicit DOM mutations).'
-      }
-      
-      div(class: 'actions') {
-        @input = input(placeholder: 'Enter list item content') {
-          value <=> [@list_presenter, :new_list_item]
-          focused <= [@list_presenter, :entering_new_list_item?, computed_by: :new_list_item]
+unless Object.const_defined?(:HelloMutationContentDataBinding) # this is only needed in sample selector app due to file reloading, but not in real apps.
+  class HelloMutationContentDataBinding
+    include Glimmer::Web::Component
+    
+    before_render do
+      @list_presenter = ListPresenter.new
+    end
+    
+    markup {
+      div {
+        h1('Hello, Mutation Content Data-Binding!')
+        
+        p {
+          'Add items to a list via content data-binding (which performs implicit DOM mutations).'
         }
         
-        button('Append list item') {
-          onclick do
-            @list_presenter.append_list_item
-          end
+        div(class: 'actions') {
+          input(placeholder: 'Enter list item content') {
+            value <=> [@list_presenter, :new_list_item]
+            focused <= [@list_presenter, :entering_new_list_item?, computed_by: :new_list_item]
+          }
+          
+          button('Append list item') {
+            disabled <= [@list_presenter, :edit_list_disabled?, computed_by: :new_list_item]
+            
+            onclick do
+              @list_presenter.append_list_item
+            end
+          }
+          
+          button('Prepend list item') {
+            disabled <= [@list_presenter, :edit_list_disabled?, computed_by: :new_list_item]
+            
+            onclick do
+              @list_presenter.prepend_list_item
+            end
+          }
+          
+          button('Insert list item') {
+            disabled <= [@list_presenter, :edit_list_disabled?, computed_by: :new_list_item]
+            
+            onclick do
+              @list_presenter.insert_list_item
+            end
+          }
+          
+          label(for: 'insert-index-input') { 'at index: ' }
+          input(id: 'insert-index-input', type: 'number') {
+            value <=> [@list_presenter, :insert_index]
+            min 0
+            max <= [@list_presenter, :max_insert_index, computed_by: :list]
+          }
         }
         
-        button('Prepend list item') {
-          onclick do
-            @list_presenter.prepend_list_item
-          end
+        ul {
+          content(@list_presenter, :list) {
+            @list_presenter.list.each do |list_item|
+              li { list_item }
+            end
+          }
         }
       }
+    }
+    
+    style {
+      r('.actions input, .actions button') {
+        margin '10px 10px 10px 0'
+      }
       
-      ul {
-        content(@list_presenter, :list) {
-          @list_presenter.list.each do |list_item|
-            li { list_item }
-          end
-        }
+      r('.actions input#insert-index-input') {
+        width 40
+      }
+      
+      r('.actions label[for=insert-index-input]') {
+        margin_left -5
       }
     }
-  }
-  
-  style {
-    r('.actions input, .actions button') {
-      margin '10px 10px 10px 0'
-    }
-  }
+  end
 end
 
 Document.ready? do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glimmer-dsl-web
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 0.10.4
 platform: ruby
 authors:
 - Andy Maleh
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.8.2
+        version: 2.8.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.8.2
+        version: 2.8.3
 - !ruby/object:Gem::Dependency
   name: glimmer-dsl-xml
   requirement: !ruby/object:Gem::Requirement