phlex-slotable 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ed2552d628d6851db0da87a5105818d55b5a28bda04d7b5dd9dc0f6fe7357a5
-  data.tar.gz: dd6b66cb419fae64ee1ea963670735a3773a6d1c26bf18c2cc1be01ad43e559b
+  metadata.gz: 47c3384e49460492a4ff914af1ecd7c6a16fa2841f90d49a4b83b84c305cf892
+  data.tar.gz: aed5afef686e5f630b98842de12b18cc9f5634dd9f099b07273a7aa281f2915a
 SHA512:
-  metadata.gz: 0aafc0d75f3907534255f8ffdc8800e8541373884c5e149afc12dfd5f1e811644c6f037ec32640501f8faec83dace3ea6368c6a17c51fe88b2e27557813f4b70
-  data.tar.gz: a5d11b19a175d1228c0ec7561986dbec0f0a976829b0b0300d599c15d32e801d9afcd4fd2dabdd3a180efccf2f12bde9673ee84744c712fa9aca7b77f3a8e412
+  metadata.gz: 02c8d0105b65526025feea5fe1aadd7851a96e8406ccb574c0b7bb45d732e54dc85c98f6fbb182af5f57ae8f404cbe17a879bafad42ef6ce9ecd0c168c286d75
+  data.tar.gz: 76a8bfd794fd7a7040bf1699db0dd3001f9d7de0cac0f641515494307a3cb370ab173588e2ba3610553c601f907d1da3990d5580702c1308c008e6d2ce11a327

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.4.0] - 2024-02-14
+- [BREAKING CHANGE] Rename `many` option to `collection`.
+
+  *stephannv*
+
+- Improve generic slot performance
+
+  *stephannv*
+
 ## [0.3.1] - 2024-02-14
 - Support Ruby 2.7
 

data/README.md

@@ -6,7 +6,21 @@
 
 Phlex::Slotable enables slots feature to [Phlex](https://www.phlex.fun/) views. Inspired by ViewComponent.
 
-## Installation
+- [What is a slot?](#what-is-a-slot)
+- [Getting started](#getting-started)
+- [Generic slot](#generic-slot)
+- [Slot collection](#slot-collection)
+- [Component slot](#component-slot)
+- [Lambda slot](#lambda-slot)
+- [Polymorphic slot](#polymorphic-slot)
+- [Development](#development)
+- [Contributing](#contributing)
+
+## What is a slot?
+
+In the context of view components, a **slot** serves as a  placeholder inside a component that can be filled with custom content.  Essentially, slots enable a component to accept external content and  autonomously organize it within its structure. This abstraction allows developers to work with components without needing to understand their internals, thereby ensuring visual consistency and improving developer experience.
+
+## Getting started
 
 Install the gem and add to the application's Gemfile by executing:
 
@@ -16,268 +30,272 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install phlex-slotable
 
-## Usage
+> [!TIP]
+> If you prefer not to add another dependency to your project, you can simply copy the [Phlex::Slotable](https://github.com/stephannv/phlex-slotable/blob/main/lib/phlex/slotable.rb) file into your project.
+
+Afterward, simply include `Phlex::Slotable` into your Phlex component and utilize `slot` macro to define the component's slots. For example:
+
+```ruby
+class MyComponent < Phlex::HTML
+  include Phlex::Slotable
+
+  slot :my_slot
+end
+```
 
-#### Basic
+Below, you will find a more detailed explanation of how to use the `slot` API.
 
-To incorportate slots into your Phlex views, include `Phlex::Slotable` and utilize `slot` class method to define them.
+## Generic slot
 
-- `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
+Any content can be passed to components through generic slots, also known as passthrough slots. To define a generic slot, use `slot :{slot_name}`. For example:
 
 ```ruby
-class BlogComponent < Phlex::HTML
+class PageComponent < Phlex::HTML
   include Phlex::Slotable
 
-  slot :header
-  slot :post, many: true
-
-  # ...
+  slot :title
 end
 ```
 
-To render a single slot, utilize the  `{slot_name}_slot` method. For example, you can render the `header_slot` using `render header_slot`.
-
-For multi-slot rendering, iterate over the `{slot_name}_slots` collection and and render each slot individually, eg. `post_slots.each { |s| render s }`.
+To render a slot, render the `{slot_name}_slot`:
 
 ```ruby
-class BlogComponent < Phlex::HTML
+class PageComponent < Phlex::HTML
   include Phlex::Slotable
 
-  slot :header
-  slot :post, many: true
+  slot :title
 
   def template
-    div id: "header" do
-      render header_slot
-    end
+    header { render title_slot }
+  end
+end
+```
 
-    div id: "main" do
-      post_slots.each do |slot|
-        p { render slot }
-      end
+To pass content to the component's slot, you should use `with_{slot_name}`:
 
-      span { "Count: #{post_slots.count}" }
-    end
+```ruby
+PageComponent.new.call do |page|
+  page.with_title do
+    h1 { "Hello World!" }
   end
 end
 ```
 
-When setting slot content, ensure to utilize the  `with_{slot_name}` method while rendering the view:
+Returning:
+
+```html
+<header>
+	<h1>Hello World!</h1>
+</header>
+```
+
+You can test if a slot has been passed to the component with `{slot_name}_slot?` method. For example:
 
 ```ruby
-class MyPage < Phlex::HTML
-  def template
-    render BlogComponent.new do |blog|
-      blog.with_header do
-        h1 { "Hello World!" }
-      end
+class PageComponent < Phlex::HTML
+  include Phlex::Slotable
+
+  slot :title
 
-      blog.with_post { "Post A" }
-      blog.with_post { "Post B" }
-      blog.with_post { "Post C" }
+  def template
+		if header_slot?
+      header { render title_slot }
+    else
+      plain "No title"
     end
   end
 end
-
-MyPage.new.call
 ```
 
-This will output:
+## Slot collection
 
-```html
-<div id="header">
-  <h1>Hello World</h1>
-</div>
-<div id="main">
-  <p>Post A</p>
-  <p>Post B</p>
-  <p>Post C</p>
+A slot collection denotes a slot capable of being rendered multiple times within a component. It has some minor differences compared to a single slot seen previously. First, you should pass `collection: true` when defining the slot:
 
-  <span>Count: 3</span>
-</div>
-```
+```ruby
+class ListComponent < Phlex::HTML
+	include Phlex::Slotable
 
-#### Predicate methods
+  slot :item, collection: true
+end
+```
 
-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.
+To render a collection of slots, iterate over the `{slot_name}_slots` collection and render each slot individually:
 
 ```ruby
-class BlogComponent < Phlex::HTML
-  include Phlex::Slotable
+class ListComponent < Phlex::HTML
+	include Phlex::Slotable
 
-  slot :header
-  slot :post, many: true
+  slot :item, collection: true
 
   def template
-    if header_slot?
-      div id: "header" do
-        render header_slot
-      end
-    end
-
-    div id: "main" do
-      if post_slots?
-        post_slots.each do |slot|
-          p { render slot }
+    if item_slots?
+      ul do
+        item_slots.each do |item_slot|
+          li { render item_slot }
         end
-
-        span { "Count: #{post_slots.count}" }
-      else
-        span { "No post yet" }
       end
     end
+
+    span { "Total: #{item_slots.size}" }
   end
 end
 ```
 
-#### View slot
-
-Slots have the capability to render other views, Simply pass the view class name to the `slot` method.
+To set slot content, use the `with_{slot_name}` method when rendering the component. Unlike the single slot,  `with_{slot_name}` can be called multiple times:
 
 ```ruby
-class HeaderComponent < Phlex::HTML
-  def initialize(size:)
-    @size = size
-  end
-
-  def template(&content)
-    h1(class: "text-#{@size}", &content)
-  end
+ListComponent.new.call do |list|
+  list.with_item { "Item A" }
+  list.with_item { "Item B" }
+  list.with_item { "Item C" }
 end
+```
 
-class PostComponent < Phlex::HTML
-  def initialize(featured:)
-    @featured = featured
-  end
+Returning:
 
-  def template(&content)
-    p(class: @featured ? "featured" : nil, &content)
-  end
+```html
+<ul>
+  <li>Item A</li>
+  <li>Item B</li>
+  <li>Item C</li>
+</ul>
+
+<span>Total: 3</span>
+```
+
+## Component slot
+
+Slots have the capability to render other components. When defining a slot, provide the name of a component class as the second argument to define a component slot
+
+```ruby
+class ListHeaderComponent < Phlex::HTML
+  # omitted code
 end
 
-class BlogComponent < Phlex::HTML
+class ListItemComponent < Phlex::HTML
+  # omitted code
+end
+
+class ListComponent < Phlex::HTML
   include Phlex::Slotable
 
-  slot :header, HeaderComponent
-  slot :post, PostComponent, many: true
+  slot :header, ListHeaderComponent
+  slot :item, ListItemComponent, collection: true
 
   def template
-    if header_slot?
-      div id: "header" do
-        render header_slot
-      end
+    div id: "header" do
+      render header_slot if header_slot?
     end
 
-    div id: "main" do
-      if post_slots?
-        post_slots.each { render slot }
-
-        span { "Count: #{post_slots.count}" }
-      else
-        span { "No post yet" }
-      end
+    ul do
+      item_slots.each { |slot| render slot }
     end
   end
 end
 
-class MyPage < Phlex::HTML
-  def template
-    render BlogComponent.new do |blog|
-      blog.with_header(size: :lg) { "Hello World!" }
+ListComponent.new.call do |list|
+  list.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
+  list.with_item(active: true) { "Item A" }
+  list.with_item { "Item B" }
+  list.with_item { "Item C" }
 end
-
-MyPage.new.call
 ```
 
-The output:
+Returning:
 
 ```html
 <div id="header">
-  <h1 class="text-lg">Hello World</h1>
-</div>
-<div id="main">
-  <p class="featured">Post A</p>
-  <p>Post B</p>
-  <p>Post C</p>
+  <h1 class="text-lg">Hello World!</h1>
 
-  <span>Count: 3</span>
+  <ul>
+    <li class="active">Item A</li>
+  	<li>Item B</li>
+	  <li>Item C</li>
+  </ul>
 </div>
 ```
 
-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
+> [!TIP]
+> You can also pass the component class as a string if your component class hasn't been defined yet. For example:
+>
+> ```ruby
+> slot :header, "HeaderComponent"
+> slot :item, "ItemComponent", collection: true
+>```
 
-  # This will not work
-  slot :header, HeaderComponent #  uninitialized constant BlogComponent::HeaderComponent
-  # You should do this
-  slot :header, "HeaderComponent"
 
-  private
+## Lambda slot
 
-  class HeaderComponent < Phlex::HTML
-    # ...
-  end
-end
-```
+Lambda slots are valuable when you prefer not to create another component for straightforward structures or when you need to render another component with specific parameters.
 
-#### 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
+class ListComponent < 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
+  slot :header, ->(size:, &content) do
+    render HeaderComponent.new(size: size, color: "primary")
+	end
+  slot :item, ->(href:, &content) { li { a(href: href, &content) } }, collection: true
 
-class MyPage < Phlex::HTML
   def template
-    render BlogComponent.new do |blog|
-      blog.with_header(size: :lg) { "Hello World!" }
+    div id: "header" do
+      render header_slot if header_slot?
+    end
 
-      blog.with_post(featured: true) { "Post A" }
-      blog.with_post { "Post B" }
-      blog.with_post { "Post C" }
+    ul do
+      item_slots.each { |slot| render slot }
     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 }
+ListComponent.new.call do |list|
+  list.with_header(size: "lg") { "Hello World!" }
 
-  def initialize(header_color:)
-    @header_color = header_color
-  end
+  list.with_item(href: "/a") { "Item A" }
+  list.with_item(href: "/b") { "Item B" }
+  list.with_item(href: "/c") { "Item C" }
 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
+Returning:
+
+```html
+<div id="header">
+  <h1 class="text-lg text-primary">Hello World!</h1>
+
+  <ul>
+    <li><a href="/a">Item A</a></li>
+    <li><a href="/b">Item B</a></li>
+    <li><a href="/c">Item C</a></li>
+  </ul>
+</div>
 ```
 
-#### 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.
+> [!TIP]
+> You can access the internal component state within lambda slots. For example
+>
+> ```ruby
+> slot :header, ->(&content) { render HeaderComponent.new(featured: @featured), &content }
+>
+> def initialize(featured:)
+>   @featured = feature
+> end
+> ```
+
+## Polymorphic slot
+
+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 IconComponent < Phlex::HTML
+  # omitted code
+end
+
+class ImageComponent < Phlex::HTML
+	# omitted code
+end
+
 class CardComponent < Phlex::HTML
   include Phlex::Slotable
 
@@ -285,73 +303,45 @@ class CardComponent < Phlex::HTML
 
   def template
     if avatar_slot?
-      figure id: "avatar" do
-        render avatar_slot
+      div 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
+User = Data.define(:image_url)
+user = User.new(image_url: "user.png")
 
-  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
+CardComponent.new.call do |card|
+  if user.image_url
+    card.with_image_avatar(src: user.image_url)
+  else
+    card.with_icon_avatar(name: :user)
   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
+Returning:
 
-  ...
-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
+```html
+<div id="avatar">
+  <img src="user.png"/>
+</div>
 ```
 
+Note that you need to use `with_{type}_{slot_name}` to set slot content. In the example above, it was used `with_image_avatar` and `with_icon_avatar`.
 
-## Roadmap
-- ✅ ~~Accept Strings as view class name~~
-- ✅ ~~Allow lambda slots~~
-- ✅ ~~Allow polymorphic slots~~
+> [!TIP]
+> You can take advantage of all the previously introduced features, such as lambda slot and slot collection:
+>
+> ```ruby
+> slot :avatar, collection: true, types: {
+>   icon: IconComponent,
+>   image: "ImageComponent",
+>   text: ->(&content) { span(class: "avatar", &content) }
+> }
+> ```
 
 ## Development
 
@@ -361,7 +351,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/stephannv/phlex-slot. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/stephannv/phlex-slotable/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/stephannv/phlex-slotable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/stephannv/phlex-slotable/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 

data/benchmark/main.rb

@@ -34,7 +34,7 @@ class SlotableList < Phlex::HTML
   include Phlex::Slotable
 
   slot :header
-  slot :item, many: true
+  slot :item, collection: true
 
   def template
     if header_slot

data/lib/phlex/slotable/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Slotable
-    VERSION = "0.3.1"
+    VERSION = "0.4.0"
   end
 end

data/lib/phlex/slotable.rb

@@ -9,35 +9,36 @@ module Phlex
     end
 
     module ClassMethods
-      def slot(slot_name, callable = nil, types: nil, many: false)
+      def slot(slot_name, callable = nil, types: nil, collection: false)
         include Phlex::DeferredRender
 
         if types
           types.each do |type, callable|
-            define_setter_method(slot_name, callable, many: many, type: type)
+            define_setter_method(slot_name, callable, collection: collection, type: type)
           end
         else
-          define_setter_method(slot_name, callable, many: many)
+          define_setter_method(slot_name, callable, collection: collection)
         end
-        define_predicate_method(slot_name, many: many)
-        define_getter_method(slot_name, many: many)
+        define_predicate_method(slot_name, collection: collection)
+        define_getter_method(slot_name, collection: collection)
       end
 
       private
 
-      def define_setter_method(slot_name, callable, many:, type: nil)
+      def define_setter_method(slot_name, callable, collection:, type: nil)
         slot_name_with_type = type ? "#{type}_#{slot_name}" : slot_name
+        signature = callable.nil? ? "(&block)" : "(*args, **kwargs, &block)"
 
-        setter_method = if many
+        setter_method = if collection
           <<-RUBY
-            def with_#{slot_name_with_type}(*args, **kwargs, &block)
+            def with_#{slot_name_with_type}#{signature}
               @#{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)
+            def with_#{slot_name_with_type}#{signature}
               @#{slot_name}_slot = #{callable_value(slot_name_with_type, callable)}
             end
           RUBY
@@ -52,8 +53,8 @@ module Phlex
         private :"__call_#{slot_name}__"
       end
 
-      def define_getter_method(slot_name, many:)
-        getter_method = if many
+      def define_getter_method(slot_name, collection:)
+        getter_method = if collection
           <<-RUBY
             def #{slot_name}_slots
               @#{slot_name}_slots ||= []
@@ -72,8 +73,8 @@ module Phlex
         class_eval(getter_method, __FILE__, __LINE__ + 1)
       end
 
-      def define_predicate_method(slot_name, many:)
-        predicate_method = if many
+      def define_predicate_method(slot_name, collection:)
+        predicate_method = if collection
           <<-RUBY
             def #{slot_name}_slots?
               #{slot_name}_slots.any?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phlex-slotable
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - stephann
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-14 00:00:00.000000000 Z
+date: 2024-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex