phlex-slotable 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1aa68f30783948c69ae6e3a9018e3e0fe828b8d1e3392208bbd926dead27761
-  data.tar.gz: f60047a296679c099258024d72e23d13a252bd4f5fd38576769716218785d962
+  metadata.gz: 6daa3c251793367884c7260e217d1df50891db3e5e5d07d3510dce8dc9dab868
+  data.tar.gz: 95a6c59d0c7571933821a8df89b76542789d16fe222677b7be48af06730bd7f1
 SHA512:
-  metadata.gz: cf5b19581bab8cb2ba50e91e44f9489b40cbdae7c0873310a98637be51cbac6212e8621a95f67bd8d5d1ad1286533b66023847c4ac4eacbe2a7f867635b2bfaa
-  data.tar.gz: d1e6a2cb591541105802d4338b857baf99ef5817aacbdd644f5a6ad3e77a4ac60669c8b5f0d9f7bdae63565e05f6fe7cbe6852e29aac88aa31366def63a5ac01
+  metadata.gz: 1c04f7d85f3068f064d8b45566de267975cd73d86d5fe7b34114865836b8cdf064cc218f01c86ddc5ffce9b942d39b1ca63f4188af23222e86f4cd6570ad516b
+  data.tar.gz: 14ac74deabd99d4af0b9370279bb0bf592d9116426c7037f40cee94c198f2d92a3dd034577218b6aaa0fa118cc7e54869966177ada7564ee96b00ca2d0e78687

data/CHANGELOG.md

@@ -1,5 +1,65 @@
 ## [Unreleased]
 
+## [0.3.0] - 2024-02-14
+
+- Match Slotable peformance with DeferredRender
+  ```
+  ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
+  Warming up --------------------------------------
+              Deferred    26.779k i/100ms
+        Slotable 0.2.0     21.636k i/100ms
+        Slotable 0.3.0    27.013k i/100ms
+  Calculating -------------------------------------
+              Deferred    267.884k (± 0.6%) i/s -      1.366M in   5.098391s
+        Slotable 0.2.0    216.193k (± 0.4%) i/s -      1.082M in   5.003961s
+        Slotable 0.3.0    270.082k (± 0.5%) i/s -      1.351M in   5.001001s
+  ```
+  *stephannv*
+
+- Allow polymorphic slots
+  ```ruby
+  class CardComponent < Phlex::HTML
+    include Phlex::Slotable
+
+    slot :avatar, types: { icon: IconComponent, image: ImageComponent }
+
+    def template
+      if avatar_slot?
+        render avatar_slot
+      end
+    end
+  end
+
+  render CardComponent.new do |card|
+    if user
+      card.with_image_avatar(src: user.image_url)
+    else
+      card.with_icon_avatar(name: :user)
+    end
+  end
+  ```
+
+  *stephannv*
+
+## [0.2.0] - 2024-02-13
+
+- Allow view slots using string as class name
+
+  *stephannv*
+
+- Allow lambda slots
+
+  *stephannv*
+
 ## [0.1.0] - 2024-02-12
+- Add single and multi slots
+
+  *stephannv*
+
+- Add generic slots
+
+  *stephannv*
+
+- Add view slots
 
-- Initial release
+  *stephannv*

data/README.md

@@ -1,25 +1,28 @@
+> [!WARNING]
+> Please note that Phlex::Slotable is currently under development and may undergo changes to its API before reaching the stable release (1.0.0). As a result, there may be breaking changes that affect its usage.
+
 # Phlex::Slotable
 
-Phlex::Slotable enables slots feature to Phlex views. Inspired by ViewComponent.
+Phlex::Slotable enables slots feature to [Phlex](https://www.phlex.fun/) views. Inspired by ViewComponent.
 
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    $ bundle add phlex-slotable
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install phlex-slotable
 
 ## Usage
 
 #### Basic
 
-Include `Phlex::Slotable` to your Phlex view and use `slot` class method to define slots.
+To incorportate slots into your Phlex views, include `Phlex::Slotable` and utilize `slot` class method to define them.
 
-- `slot :slot_name` defines a single slot that will be rendered at most once per component
-- `slot :slot_name, many: true` defines a slot that can be rendered multiple times per component
+- `slot :slot_name` declaration establishes a single slot intended for rendering once within a view
+- `slot :slot_name, many: true` denotes a slot capable of being rendered multiple times within a view
 
 ```ruby
 class BlogComponent < Phlex::HTML
@@ -32,9 +35,9 @@ class BlogComponent < Phlex::HTML
 end
 ```
 
-To render a single slot, render `{slot_name}_slot`, eg. `render header_slot`.
+To render a single slot, utilize the  `{slot_name}_slot` method. For example, you can render the `header_slot` using `render header_slot`.
 
-To render a multi slot, iterate over `{slot_name}_slots` and render each element, eg. `post_slots.each { |s| render s }`
+For multi-slot rendering, iterate over the `{slot_name}_slots` collection and and render each slot individually, eg. `post_slots.each { |s| render s }`.
 
 ```ruby
 class BlogComponent < Phlex::HTML
@@ -44,11 +47,11 @@ class BlogComponent < Phlex::HTML
   slot :post, many: true
 
   def template
-  	div id: "header" do
+    div id: "header" do
       render header_slot
     end
 
-		div id: "main" do
+    div id: "main" do
       post_slots.each do |slot|
         p { render slot }
       end
@@ -59,7 +62,7 @@ class BlogComponent < Phlex::HTML
 end
 ```
 
-To set slot content, you need to use `with_{slot_name}` when rendering the view:
+When setting slot content, ensure to utilize the  `with_{slot_name}` method while rendering the view:
 
 ```ruby
 class MyPage < Phlex::HTML
@@ -96,7 +99,7 @@ This will output:
 
 #### Predicate methods
 
-You can check if a slot has been passed to the component using `{slot_name}_slot?` when it is a single slot, or `{slot_name}_slots?` when it is a multi slot.
+You can verify whether a slot has been provided to the view using `{slot_name}_slot?` for single slots or `{slot_name}_slots?` when for multi-slots.
 
 ```ruby
 class BlogComponent < Phlex::HTML
@@ -106,13 +109,13 @@ class BlogComponent < Phlex::HTML
   slot :post, many: true
 
   def template
-  	if header_slot?
+    if header_slot?
       div id: "header" do
         render header_slot
       end
     end
 
-		div id: "main" do
+    div id: "main" do
       if post_slots?
         post_slots.each do |slot|
           p { render slot }
@@ -129,11 +132,11 @@ end
 
 #### View slot
 
-Slots can render other views, you just need to pass the view class name to `slot` method.
+Slots have the capability to render other views, Simply pass the view class name to the `slot` method.
 
 ```ruby
 class HeaderComponent < Phlex::HTML
-	def initialize(size:)
+  def initialize(size:)
     @size = size
   end
 
@@ -143,7 +146,7 @@ class HeaderComponent < Phlex::HTML
 end
 
 class PostComponent < Phlex::HTML
-	def initialize(featured:)
+  def initialize(featured:)
     @featured = featured
   end
 
@@ -159,13 +162,13 @@ class BlogComponent < Phlex::HTML
   slot :post, PostComponent, many: true
 
   def template
-  	if header_slot?
+    if header_slot?
       div id: "header" do
         render header_slot
       end
     end
 
-		div id: "main" do
+    div id: "main" do
       if post_slots?
         post_slots.each { render slot }
 
@@ -207,11 +210,147 @@ The output:
 </div>
 ```
 
-## Roadmap
+You can pass the class name as a string for cases where the class isn't evaluated yet, such as with inner classes. For example:
+```ruby
+class BlogComponent < Phlex::HTML
+  include Phlex::Slotable
+
+  # This will not work
+  slot :header, HeaderComponent #  uninitialized constant BlogComponent::HeaderComponent
+  # You should do this
+  slot :header, "HeaderComponent"
+
+  private
+
+  class HeaderComponent < Phlex::HTML
+    # ...
+  end
+end
+```
+
+#### Lambda slots
+Lambda slots are valuable when you prefer not to create another component for straightforward structures or when you need to render another view with specific parameters
+```ruby
+
+class BlogComponent < Phlex::HTML
+  include Phlex::Slotable
+
+  slot :header, ->(size:, &content) { render HeaderComponent.new(size: size, color: "blue"), &content }
+  slot :post, ->(featured:, &content) { span(class: featured ? "featured" : nil, &content) }, many: true
+end
+
+class MyPage < Phlex::HTML
+  def template
+    render BlogComponent.new do |blog|
+      blog.with_header(size: :lg) { "Hello World!" }
+
+      blog.with_post(featured: true) { "Post A" }
+      blog.with_post { "Post B" }
+      blog.with_post { "Post C" }
+    end
+  end
+end
+```
+
+You can access the internal view state within lambda slots. For example:
+```ruby
+class BlogComponent < Phlex::HTML
+  include Phlex::Slotable
+
+  slot :header, ->(size:, &content) { render HeaderComponent.new(size: size, color: @header_color), &content }
+
+  def initialize(header_color:)
+    @header_color = header_color
+  end
+end
+
+class MyPage < Phlex::HTML
+  def template
+    render BlogComponent.new(header_color: "red") do |blog|
+      blog.with_header(size: :lg) { "Hello World!" }
+    end
+  end
+end
+```
+
+#### Polymorphic slots
+Polymorphic slots can render one of several possible slots, allowing for flexibility in component content. This feature is particularly useful when you require a fixed structure but need to accommodate different types of content. To implement this, simply pass a types hash containing the types along with corresponding slot definitions.
+
+```ruby
+class CardComponent < Phlex::HTML
+  include Phlex::Slotable
 
-[] Accepts Strings as view class name
-[] Allow lambda slots
-[] Allow polymorphic slots
+  slot :avatar, types: { icon: IconComponent, image: ImageComponent }
+
+  def template
+    if avatar_slot?
+      figure id: "avatar" do
+        render avatar_slot
+      end
+    end
+  end
+end
+```
+
+This allows you to set the icon slot using `with_icon_avatar` or the image slot using `with_image_avatar`:
+```ruby
+class UserCardComponent < Phlex::HTML
+  def initialize(user:)
+    @user = user
+  end
+
+  def template
+    render CardComponent.new do |card|
+      if @user.image?
+        card.with_image_avatar(src: @user.image)
+      else
+        card.with_icon_avatar(name: :user)
+      end
+    end
+  end
+end
+```
+
+Please note that you can still utilize the other slot definition APIs:
+```ruby
+class CardComponent < Phlex::HTML
+  include Phlex::Slotable
+
+  slot :avatar, types: {
+    icon: IconComponent,
+    image: "ImageComponent",
+    text: ->(size:, &content) { span(class: "text-#{size}", &content) }
+  }, many: true
+
+  def template
+    if avatar_slots?
+      avatar_slots.each do |slot|
+        render slot
+      end
+    end
+
+    span { "Count: #{avatar_slots.size}" }
+  end
+
+  ...
+end
+
+class UsersCardComponent < Phlex::HTML
+  def template
+    render CardComponent.new do |card|
+      card.with_image_avatar(src: @user.image)
+      card.with_icon_avatar(name: :user)
+      card.with_text_avatar(size: :lg) { "SV" }
+    end
+  end
+end
+```
+
+
+## Roadmap
+- ✅ ~~Accept Strings as view class name~~
+- ✅ ~~Allow lambda slots~~
+- ✅ ~~Allow polymorphic slots~~
 
 ## Development
 

data/benchmark/main.rb

@@ -0,0 +1,105 @@
+require "benchmark"
+require "benchmark/ips"
+require_relative "../lib/phlex/slotable"
+
+class DeferredList < Phlex::HTML
+  include Phlex::DeferredRender
+
+  def initialize
+    @items = []
+  end
+
+  def template
+    if @header
+      h1(class: "header", &@header)
+    end
+
+    ul do
+      @items.each do |item|
+        li { render(item) }
+      end
+    end
+  end
+
+  def header(&block)
+    @header = block
+  end
+
+  def with_item(&content)
+    @items << content
+  end
+end
+
+class SlotableList < Phlex::HTML
+  include Phlex::Slotable
+
+  slot :header
+  slot :item, many: true
+
+  def template
+    if header_slot
+      h1(class: "header", &header_slot)
+    end
+
+    ul do
+      item_slots.each do |slot|
+        li { render(slot) }
+      end
+    end
+  end
+end
+
+class DeferredListExample < Phlex::HTML
+  def template
+    render DeferredList.new do |list|
+      list.header do
+        "Header"
+      end
+
+      list.with_item do
+        "One"
+      end
+
+      list.with_item do
+        "two"
+      end
+    end
+  end
+end
+
+class SlotableListExample < Phlex::HTML
+  def template
+    render SlotableList.new do |list|
+      list.with_header do
+        "Header"
+      end
+
+      list.with_item do
+        "One"
+      end
+
+      list.with_item do
+        "two"
+      end
+    end
+  end
+end
+
+puts RUBY_DESCRIPTION
+
+deferred_list = DeferredListExample.new.call
+slotable_list = SlotableListExample.new.call
+
+raise unless deferred_list == slotable_list
+
+Benchmark.bmbm do |x|
+  x.report("Deferred") { 1_000_000.times { DeferredListExample.new.call } }
+  x.report("Slotable") { 1_000_000.times { SlotableListExample.new.call } }
+end
+
+puts
+
+Benchmark.ips do |x|
+  x.report("Deferred") { DeferredListExample.new.call }
+  x.report("Slotable") { SlotableListExample.new.call }
+end

data/lib/phlex/slotable/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Slotable
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/phlex/slotable.rb

@@ -9,50 +9,91 @@ module Phlex
     end
 
     module ClassMethods
-      def slot(slot_name, callable = nil, many: false)
+      def slot(slot_name, callable = nil, types: nil, many: false)
         include Phlex::DeferredRender
 
-        if many
-          define_method :"with_#{slot_name}" do |*args, **kwargs, &block|
-            instance_variable_set(:"@#{slot_name}_slots", []) unless instance_variable_defined?(:"@#{slot_name}_slots")
+        if types
+          types.each do |type, callable|
+            define_setter_method(slot_name, callable, many: many, type: type)
+          end
+        else
+          define_setter_method(slot_name, callable, many: many)
+        end
+        define_predicate_method(slot_name, many: many)
+        define_getter_method(slot_name, many: many)
+      end
 
-            value = case callable
-            when nil
-              block
-            else
-              callable.new(*args, **kwargs, &block)
+      private
+
+      def define_setter_method(slot_name, callable, many:, type: nil)
+        slot_name_with_type = type ? "#{type}_#{slot_name}" : slot_name
+
+        setter_method = if many
+          <<-RUBY
+            def with_#{slot_name_with_type}(*args, **kwargs, &block)
+              @#{slot_name}_slots ||= []
+              @#{slot_name}_slots << #{callable_value(slot_name_with_type, callable)}
             end
+          RUBY
+        else
+          <<-RUBY
+            def with_#{slot_name_with_type}(*args, **kwargs, &block)
+              @#{slot_name}_slot = #{callable_value(slot_name_with_type, callable)}
+            end
+          RUBY
+        end
 
-            instance_variable_get(:"@#{slot_name}_slots") << value
-          end
+        class_eval(setter_method, __FILE__, __LINE__ + 1)
+        define_lambda_method(slot_name_with_type, callable) if callable.is_a?(Proc)
+      end
 
-          define_method :"#{slot_name}_slots?" do
-            !send(:"#{slot_name}_slots").empty?
-          end
-          private :"#{slot_name}_slots?"
+      def define_lambda_method(slot_name, callable)
+        define_method :"__call_#{slot_name}__", &callable
+        private :"__call_#{slot_name}__"
+      end
 
-          define_method :"#{slot_name}_slots" do
-            instance_variable_get(:"@#{slot_name}_slots") || instance_variable_set(:"@#{slot_name}_slots", [])
-          end
-          private :"#{slot_name}_slots"
-        else
-          define_method :"with_#{slot_name}" do |*args, **kwargs, &block|
-            value = case callable
-            when nil
-              block
-            else
-              callable.new(*args, **kwargs, &block)
+      def define_getter_method(slot_name, many:)
+        getter_method = if many
+          <<-RUBY
+            def #{slot_name}_slots
+              @#{slot_name}_slots ||= []
             end
+            private :#{slot_name}_slots
+          RUBY
+        else
+          <<-RUBY
+            def #{slot_name}_slot = @#{slot_name}_slot
+            private :#{slot_name}_slot
+          RUBY
+        end
 
-            instance_variable_set(:"@#{slot_name}_slot", value)
-          end
+        class_eval(getter_method, __FILE__, __LINE__ + 1)
+      end
 
-          define_method :"#{slot_name}_slot?" do
-            !instance_variable_get(:"@#{slot_name}_slot").nil?
-          end
-          private :"#{slot_name}_slot?"
+      def define_predicate_method(slot_name, many:)
+        predicate_method = if many
+          <<-RUBY
+            def #{slot_name}_slots? = #{slot_name}_slots.any?
+            private :#{slot_name}_slots?
+          RUBY
+        else
+          <<-RUBY
+            def #{slot_name}_slot? = !#{slot_name}_slot.nil?
+            private :#{slot_name}_slot?
+          RUBY
+        end
 
-          attr_reader :"#{slot_name}_slot"
+        class_eval(predicate_method, __FILE__, __LINE__ + 1)
+      end
+
+      def callable_value(slot_name, callable)
+        case callable
+        when nil
+          %(block)
+        when Proc
+          %(-> { self.class.instance_method(:"__call_#{slot_name}__").bind_call(self, *args, **kwargs, &block) })
+        else
+          %(#{callable}.new(*args, **kwargs, &block))
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phlex-slotable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - stephann
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-12 00:00:00.000000000 Z
+date: 2024-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex
@@ -37,6 +37,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmark/main.rb
 - lib/phlex/slotable.rb
 - lib/phlex/slotable/version.rb
 homepage: https://github.com/stephannv/phlex-slotable