glimmer-dsl-web 0.0.8 → 0.0.9

data/VERSION

@@ -1 +1 @@
-0.0.8
+0.0.9

data/glimmer-dsl-web.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: glimmer-dsl-web 0.0.8 ruby lib
+# stub: glimmer-dsl-web 0.0.9 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "glimmer-dsl-web".freeze
-  s.version = "0.0.8".freeze
+  s.version = "0.0.9".freeze
 
   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-01-03"
+  s.date = "2024-01-05"
   s.description = "Glimmer DSL for Web (Ruby in the Browser Web GUI Frontend Library) - Enables frontend GUI development with Ruby by adopting a DSL that follows web-like HTML syntax, enabling the transfer of HTML/CSS/JS skills to Ruby frontend development. This library relies on Opal Ruby.".freeze
   s.email = "andy.am@gmail.com".freeze
   s.extra_rdoc_files = [
@@ -31,6 +31,7 @@ Gem::Specification.new do |s|
     "lib/glimmer-dsl-web/ext/date.rb",
     "lib/glimmer-dsl-web/ext/exception.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_content_data_binding.rb",
     "lib/glimmer-dsl-web/samples/hello/hello_data_binding.rb",
     "lib/glimmer-dsl-web/samples/hello/hello_form.rb",
@@ -40,6 +41,7 @@ Gem::Specification.new do |s|
     "lib/glimmer/config/opal_logger.rb",
     "lib/glimmer/data_binding/element_binding.rb",
     "lib/glimmer/dsl/web/bind_expression.rb",
+    "lib/glimmer/dsl/web/component_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",
@@ -52,6 +54,7 @@ Gem::Specification.new do |s|
     "lib/glimmer/dsl/web/shine_data_binding_expression.rb",
     "lib/glimmer/util/proc_tracker.rb",
     "lib/glimmer/web.rb",
+    "lib/glimmer/web/component.rb",
     "lib/glimmer/web/element_proxy.rb",
     "lib/glimmer/web/event_proxy.rb",
     "lib/glimmer/web/listener_proxy.rb"

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

@@ -0,0 +1,30 @@
+require 'glimmer/dsl/parent_expression'
+require 'glimmer/web/component'
+
+module Glimmer
+  module DSL
+    module Web
+      class ComponentExpression < Expression
+        include ParentExpression
+
+        def can_interpret?(parent, keyword, *args, &block)
+          !!Glimmer::Web::Component.for(keyword)
+        end
+  
+        def interpret(parent, keyword, *args, &block)
+          custom_widget_class = Glimmer::Web::Component.for(keyword)
+          custom_widget_class.new(parent, args, {}, &block)
+        end
+  
+        def add_content(parent, keyword, *args, &block)
+          # TODO consider avoiding source_location since it does not work in Opal
+          if block.source_location && (block.source_location == parent.content&.__getobj__&.source_location)
+            parent.content.call(parent) unless parent.content.called?
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,7 @@ require 'glimmer/dsl/web/bind_expression'
 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'
 
 module Glimmer
   module DSL
@@ -15,6 +16,7 @@ module Glimmer
       Engine.add_dynamic_expressions(
        Web,
        %w[
+         component
          listener
          data_binding
          property

data/lib/glimmer/web/component.rb

@@ -0,0 +1,317 @@
+# 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/error'
+require 'glimmer/util/proc_tracker'
+require 'glimmer/data_binding/observer'
+require 'glimmer/data_binding/observable_model'
+
+module Glimmer
+  module Web
+    module Component
+      include DataBinding::ObservableModel
+      
+      module ClassMethods
+        include Glimmer
+        
+        # Allows defining convenience option accessors for an array of option names
+        # Example: `options :color1, :color2` defines `#color1` and `#color2`
+        # where they return the instance values `options[:color1]` and `options[:color2]`
+        # respectively.
+        # Can be called multiple times to set more options additively.
+        # When passed no arguments, it returns list of all option names captured so far
+        def options(*new_options)
+          new_options = new_options.compact.map(&:to_s).map(&:to_sym)
+          if new_options.empty?
+            @options ||= {} # maps options to defaults
+          else
+            new_options = new_options.reduce({}) {|new_options_hash, new_option| new_options_hash.merge(new_option => nil)}
+            @options = options.merge(new_options)
+            def_option_attr_accessors(new_options)
+          end
+        end
+
+        def option(new_option, default: nil)
+          new_option = new_option.to_s.to_sym
+          new_options = {new_option => default}
+          '@options = options.merge(new_options)'
+          @options = options.merge(new_options)
+          'def_option_attr_accessors(new_options)'
+          def_option_attr_accessors(new_options)
+        end
+
+        def def_option_attr_accessors(new_options)
+          new_options.each do |option, default|
+            define_method(option) do
+              options[:"#{option}"]
+            end
+            define_method("#{option}=") do |option_value|
+              self.options[:"#{option}"] = option_value
+            end
+          end
+        end
+
+        def before_render(&block)
+          @before_render_blocks ||= []
+          @before_render_blocks << block
+        end
+
+        def markup(&block)
+          @markup_block = block
+        end
+
+        def after_render(&block)
+          @after_render_blocks ||= []
+          @after_render_blocks << block
+        end
+        
+        def keyword
+          self.name.underscore.gsub('::', '__')
+        end
+        
+        # Returns shortcut keyword to use for this component (keyword minus namespace)
+        def shortcut_keyword
+          self.name.underscore.gsub('::', '__').split('__').last
+        end
+        
+        def render(*args)
+          rendered_component = send(keyword)
+          rendered_component.render(*args)
+          rendered_component
+        end
+      end
+      
+      # This module was only created to prevent Glimmer from checking method_missing first
+      module GlimmerSupersedable
+        def method_missing(method_name, *args, &block)
+          Glimmer::DSL::Engine.interpret(method_name, *args, &block)
+        rescue
+          super(method_name, *args, &block)
+        end
+      end
+      
+      class << self
+        def included(klass)
+          if !klass.ancestors.include?(GlimmerSupersedable)
+            klass.extend(ClassMethods)
+            klass.include(Glimmer)
+            klass.prepend(GlimmerSupersedable)
+            Glimmer::Web::Component.add_component_namespaces_for(klass)
+          end
+        end
+      
+        def for(underscored_component_name)
+          extracted_namespaces = underscored_component_name.
+            to_s.
+            split(/__/).map do |namespace|
+              namespace.camelcase(:upper)
+            end
+          Glimmer::Web::Component.component_namespaces.each do |base|
+            extracted_namespaces.reduce(base) do |result, namespace|
+              if !result.constants.include?(namespace)
+                namespace = result.constants.detect {|c| c.to_s.upcase == namespace.to_s.upcase } || namespace
+              end
+              begin
+                constant = result.const_get(namespace)
+                return constant if constant&.respond_to?(:ancestors) &&
+                                   (
+                                     constant&.ancestors&.to_a.include?(Glimmer::Web::Component) ||
+                                     # TODO checking GlimmerSupersedable as a hack because when a class is loaded twice (like when loading samples
+                                     # by reloading ruby files), it loses its Glimmer::Web::Component ancestor as a bug in Opal
+                                     # but somehow the prepend module remains
+                                     constant&.ancestors&.to_a.include?(GlimmerSupersedable)
+                                   )
+                constant
+              rescue => e
+                # Glimmer::Config.logger.debug {"#{e.message}\n#{e.backtrace.join("\n")}"}
+                result
+              end
+            end
+          end
+          raise "#{underscored_component_name} has no Glimmer web component class!"
+        rescue => e
+          Glimmer::Config.logger.debug {e.message}
+          Glimmer::Config.logger.debug {"#{e.message}\n#{e.backtrace.join("\n")}"}
+          nil
+        end
+ 
+        def add_component_namespaces_for(klass)
+          Glimmer::Web::Component.namespaces_for_class(klass).drop(1).each do |namespace|
+            Glimmer::Web::Component.component_namespaces << namespace
+          end
+        end
+
+        def namespaces_for_class(m)
+          return [m] if m.name.nil?
+          namespace_constants = m.name.split(/::/).map(&:to_sym)
+          namespace_constants.reduce([Object]) do |output, namespace_constant|
+            output += [output.last.const_get(namespace_constant)]
+          end[1..-1].uniq.reverse
+        end
+
+        def component_namespaces
+          @component_namespaces ||= reset_component_namespaces
+        end
+
+        def reset_component_namespaces
+          @component_namespaces = Set[Object, Glimmer::Web]
+        end
+      end
+      # <- end of class methods
+      
+
+      attr_reader :markup_root, :parent, :options
+      alias parent_proxy parent
+
+      def initialize(parent, args, options, &content)
+        @parent = parent
+        options = args.delete_at(-1) if args.is_a?(Array) && args.last.is_a?(Hash)
+        if args.is_a?(Hash)
+          options = args
+          args = []
+        end
+        options ||= {}
+        @args = args
+        options ||= {}
+        @options = self.class.options.merge(options)
+        @content = Util::ProcTracker.new(content) if content
+        execute_hooks('before_render')
+        markup_block = self.class.instance_variable_get("@markup_block")
+        raise Glimmer::Error, 'Invalid Glimmer web component for having no markup! Please define markup block!' if markup_block.nil?
+        @markup_root = instance_exec(&markup_block)
+        @parent ||= @markup_root.parent
+        raise Glimmer::Error, 'Invalid Glimmer web component for having an empty markup! Please fill markup block!' if @markup_root.nil?
+        execute_hooks('after_render')
+      end
+      
+      # Subclasses may override to perform post initialization work on an added child
+      def post_initialize_child(child)
+        # No Op by default
+      end
+
+      def can_handle_observation_request?(observation_request)
+        observation_request = observation_request.to_s
+        result = false
+        if observation_request.start_with?('on_updated_')
+          property = observation_request.sub(/^on_updated_/, '')
+          result = can_add_observer?(property)
+        end
+        result || markup_root&.can_handle_observation_request?(observation_request)
+      end
+
+      def handle_observation_request(observation_request, block)
+        observation_request = observation_request.to_s
+        if observation_request.start_with?('on_updated_')
+          property = observation_request.sub(/^on_updated_/, '') # TODO look into eliminating duplication from above
+          add_observer(DataBinding::Observer.proc(&block), property) if can_add_observer?(property)
+        else
+          markup_root.handle_observation_request(observation_request, block)
+        end
+      end
+
+      def can_add_observer?(attribute_name)
+        has_instance_method?(attribute_name) || has_instance_method?("#{attribute_name}?") || @markup_root.can_add_observer?(attribute_name)
+      end
+
+      def add_observer(observer, attribute_name)
+        if has_instance_method?(attribute_name)
+          super(observer, attribute_name)
+        else
+          @markup_root.add_observer(observer, attribute_name)
+        end
+      end
+
+      def has_attribute?(attribute_name, *args)
+        has_instance_method?(attribute_setter(attribute_name)) ||
+          @markup_root.has_attribute?(attribute_name, *args)
+      end
+
+      def set_attribute(attribute_name, *args)
+        if has_instance_method?(attribute_setter(attribute_name))
+          send(attribute_setter(attribute_name), *args)
+        else
+          @markup_root.set_attribute(attribute_name, *args)
+        end
+      end
+
+      # This method ensures it has an instance method not coming from Glimmer DSL
+      def has_instance_method?(method_name)
+        respond_to?(method_name) and
+          !markup_root&.respond_to?(method_name) and
+          !method(method_name)&.source_location&.first&.include?('glimmer/dsl/engine.rb') and
+          !method(method_name)&.source_location&.first&.include?('glimmer/web/element_proxy.rb')
+      end
+
+      def get_attribute(attribute_name)
+        if has_instance_method?(attribute_name)
+          send(attribute_name)
+        else
+          @markup_root.get_attribute(attribute_name)
+        end
+      end
+
+      def attribute_setter(attribute_name)
+        "#{attribute_name}="
+      end
+      
+      def render(*args)
+        # this method is defined to prevent displaying a harmless Glimmer no keyword error as an annoying useless warning
+        @markup_root&.render(*args)
+      end
+      
+      # Returns content block if used as an attribute reader (no args)
+      # Otherwise, if a block is passed, it adds it as content to this Glimmer web component
+      def content(&block)
+        if block_given?
+          Glimmer::DSL::Engine.add_content(self, Glimmer::DSL::Web::ComponentExpression.new, self.class.keyword, &block)
+        else
+          @content
+        end
+      end
+
+      def method_missing(method_name, *args, &block)
+        if can_handle_observation_request?(method_name)
+          handle_observation_request(method_name, block)
+        elsif markup_root.respond_to?(method_name, true)
+          markup_root.send(method_name, *args, &block)
+        else
+          super(method_name, *args, &block)
+        end
+      end
+
+      alias local_respond_to? respond_to_missing?
+      def respond_to_missing?(method_name, include_private = false)
+        super(method_name, include_private) or
+          can_handle_observation_request?(method_name) or
+          markup_root.respond_to?(method_name, include_private)
+      end
+
+      private
+
+      def execute_hooks(hook_name)
+        self.class.instance_variable_get("@#{hook_name}_blocks")&.each do |hook_block|
+          instance_exec(&hook_block)
+        end
+      end
+    end
+  end
+end

data/lib/glimmer/web/element_proxy.rb

@@ -223,10 +223,16 @@ module Glimmer
         end
       end
       
-      def render(custom_parent_dom_element: nil, brand_new: false)
+      def render(parent_selector = nil, custom_parent_dom_element: nil, brand_new: false)
+        options[:parent] = parent_selector if !parent_selector.to_s.empty?
+        if !options[:parent].to_s.empty?
+          # ensure element is orphaned as it is becoming a top-level root element
+          @parent&.post_remove_child(self)
+          @parent = nil
+        end
         the_parent_dom_element = custom_parent_dom_element || parent_dom_element
         old_element = dom_element
-        brand_new = @dom.nil? || old_element.empty? || brand_new
+        brand_new = @dom.nil? || old_element.empty? || !options[:parent].to_s.empty? || brand_new
         build_dom(layout: !custom_parent_dom_element) # TODO handle custom parent layout by passing parent instead of parent dom element
         if brand_new
           # TODO make a method attach to allow subclasses to override if needed

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

@@ -0,0 +1,223 @@
+# 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 GUI DSL keyword that matches the lowercase underscored version
+# of the name of the class. AddressForm generates address_form keyword, which can be used
+# elsewhere in Glimmer GUI DSL code as done inside AddressPage below.
+class AddressForm
+  include Glimmer::Web::Component
+  
+  option :address
+  
+  # Optionally, you can execute code before rendering markup.
+  # This is useful for pre-setup of variables (e.g. Models) that you would use in the markup.
+  #
+  # before_render do
+  # end
+  
+  # Optionally, you can execute code after rendering markup.
+  # This is useful for post-setup of extra Model listeners that would interact with the
+  # markup elements and expect them to be rendered already.
+  #
+  # after_render do
+  # end
+  
+  # markup block provides the content of the
+  markup {
+    div {
+      div(style: 'display: grid; grid-auto-columns: 80px 260px;') { |address_div|
+        label('Full Name: ', for: 'full-name-field')
+        input(id: 'full-name-field') {
+          value <=> [address, :full_name]
+        }
+        
+        @somelabel = label('Street: ', for: 'street-field')
+        input(id: 'street-field') {
+          value <=> [address, :street]
+        }
+        
+        label('Street 2: ', for: 'street2-field')
+        textarea(id: 'street2-field') {
+          value <=> [address, :street2]
+        }
+        
+        label('City: ', for: 'city-field')
+        input(id: 'city-field') {
+          value <=> [address, :city]
+        }
+        
+        label('State: ', for: 'state-field')
+        select(id: 'state-field') {
+          Address::STATES.each do |state_code, state|
+            option(value: state_code) { state }
+          end
+
+          value <=> [address, :state_code]
+        }
+        
+        label('Zip Code: ', for: 'zip-code-field')
+        input(id: 'zip-code-field', type: 'number', min: '0', max: '99999') {
+          value <=> [address, :zip_code,
+                      on_write: :to_s,
+                    ]
+        }
+        
+        style {
+          <<~CSS
+            #{address_div.selector} * {
+              margin: 5px;
+            }
+            #{address_div.selector} input, #{address_div.selector} select {
+              grid-column: 2;
+            }
+          CSS
+        }
+      }
+      
+      div(style: 'margin: 5px') {
+        inner_text <= [address, :summary,
+                        computed_by: address.members + ['state_code'],
+                      ]
+      }
+    }
+  }
+end
+
+# AddressPage Glimmer Web Component (View component)
+#
+# This View component represents the main page being rendered,
+# as done by its `render` class method below
+class AddressPage
+  include Glimmer::Web::Component
+  
+  before_render do
+    @shipping_address = Address.new(
+      full_name: 'Johnny Doe',
+      street: '3922 Park Ave',
+      street2: 'PO BOX 8382',
+      city: 'San Diego',
+      state: 'California',
+      zip_code: '91913',
+    )
+    @billing_address = Address.new(
+      full_name: 'John C Doe',
+      street: '123 Main St',
+      street2: 'Apartment 3C',
+      city: 'San Diego',
+      state: 'California',
+      zip_code: '91911',
+    )
+  end
+  
+  markup {
+    div {
+      h1('Shipping Address')
+      
+      address_form(address: @shipping_address)
+      
+      h1('Billing Address')
+      
+      address_form(address: @billing_address)
+    }
+  }
+end
+
+Document.ready? do
+  # renders a top-level (root) AddressPage component
+  AddressPage.render
+end