protos 0.2.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 939a00cb6d422dc749d734683f4eceedf4c1857f21ab770dae704a99e06cdf8a
-  data.tar.gz: 60525463c5531256d9cac2139791b112c477b746a8ed2a643d29856fe548517a
+  metadata.gz: 2e1c2bbb97997971d3380fb5846b8720a01d50d61942a9dea5a00e5d19d2c416
+  data.tar.gz: 10c0adb3dfeef8488ae235b0b7d4ec9567f7011ec5bbe0707d33bff3d6cc0049
 SHA512:
-  metadata.gz: '094affdf956f0ff06aba676408ee34d20e6af8ed5ac92afa04576bbc52b83499e491bfd74c3b27c281d20f32fcada8dbad27ec2fbedcb79cb519e9e0a318d2e7'
-  data.tar.gz: 953db1b5c57a9202a3f87e0a3ac8e32ed226f48c85588b7d1041559fd8a0749952c76619cc85eb075717b697623bb1dc045cf0dcc9c23370c1622e67c460d993
+  metadata.gz: f8b800214d96624b909934dde77611d12e55aca2eeac34c499d4f905f3fd5e39ca4d56b8130e9b7ffe0240292b27a852842bce3aef47b22607ef68c00d2df675
+  data.tar.gz: 42a866cc6f7d50169d464b6a016c4852e37634c63003552f732d149725289580c8b031b3d3ce29c6c0f1eb93bd18b73d2cf46f1ff1588cef9a0e39ebe7892a9b

data/.rubocop.yml

@@ -1,12 +1,12 @@
 require:
   - rubocop-inhouse
 
-AllCops:
-  TargetRubyVersion: 3.1
-
 inherit_gem:
   rubocop-inhouse:
     - config/default.yml
 
-Style/ConstantVisibility:
-  Enabled: false
+AllCops:
+  TargetRubyVersion: 3.2
+
+Naming/BlockForwarding:
+  EnforcedStyle: anonymous

data/CHANGELOG.md

@@ -9,3 +9,14 @@
 - Chose to move away from daisyUI dropdown defaults as they have problems
   displaying properly in too many situations
 - Opted for using a protos-stimulus controller that uses tippy.js
+
+## [0.3.0] - 2024-04-06
+
+- Updates to phlex v0.10 by changing all `template` methods to `view_template`
+- Improvements to README
+
+## [0.4.0] - ???
+
+- Phlex discord didn't like all the calls to `render`
+- Apparently `render` is called differently within ERB
+- Suggested to change all calls to immediately render, would improve ergonomics

data/README.md

@@ -25,11 +25,11 @@ Other Phlex based UI libraries worth checking out:
 A protos component follows some conventions that make them easy to work with as
 components in your app.
 
-Every UI component library will have a tension between being too general or
-narrow to be useful. Making components that look good out of the box can make
-them hard to customize.
+Every UI component library will have a tension between being too general to fit
+in your app or too narrow to be useful. Making components that look good out of
+the box can make them hard to customize.
 
-We try and resolve this tensions by making the components have a minimal style
+We try and resolve this tension by making these components have a minimal style
 that can be easily overridden using some ergonomic conventions.
 
 There are 3 core conventions:
@@ -40,11 +40,16 @@ There are 3 core conventions:
 ### Slots and themes
 
 Components are styled with `css` slots that are filled with values from
-a `theme`:
+a `theme`.
+
+You define a theme for your component by defining a `#theme` method that returns
+a hash. This hash will be merged with any theme provided when rendering your
+component. This allows you to easily override styles for your components
+depending on their context.
 
 ```ruby
 class List < Protos::Component
-  def template
+  def view_template
     ul(class: css[:list]) do
       li(class: css[:item]) { "Item 1" }
       li(class: css[:item]) { "Item 2" }
@@ -53,31 +58,8 @@ class List < Protos::Component
 
   def theme
     {
-      list: tokens("space-y-4"),
-      item: tokens("font-bold", "text-2xl")
-    }
-  end
-end
-```
-
-Here we are using conditional `tokens` from Phlex but you can also use
-simple strings.
-
-If you want to change the method we define our default theme you can override the
-`theme_method` on the class:
-
-```ruby
-class List < Protos::Component
-  theme_method :custom_theme
-
-  # ...
-
-  private
-
-  def custom_theme
-    {
-      list: tokens("space-y-4"),
-      item: tokens("font-bold", "text-2xl")
+      list: tokens("space-y-4"), # We can use `#tokens` from phlex (recommended)
+      item: "font-bold text-2xl" # Or just plain old strings
     }
   end
 end
@@ -137,18 +119,40 @@ The new `css[:item]` slot would be:
 <li class="font-bold">Item 1</li>
 ```
 
+If you want to change the method we define our default theme you can override the
+`theme_method` on the class:
+
+```ruby
+class List < Protos::Component
+  theme_method :custom_theme
+
+  # ...
+
+  private
+
+  def custom_theme
+    {
+      list: tokens("space-y-4"),
+      item: tokens("font-bold", "text-2xl")
+    }
+  end
+end
+```
+
 ### Attrs and default attrs
 
 By convention, all components spread in an `attrs` hash on their outermost
 element of the component.
 
 By doing this we enable 2 main conveniences:
-1. We can pass `class` when initializing the component
-2. We can add default attributes that can be merged with defaults
+1. We can pass a `class` keyword when initializing the component which will be
+   merged safely into the `css[:container]` slot
+2. We can add default attributes that are safely merged with any provided to the
+   component when its being initialized
 
 ```ruby
 class List < Protos::Component
-  def template
+  def view_template
     ul(**attrs) do
       # ...
     end
@@ -158,9 +162,7 @@ class List < Protos::Component
 
   def default_attrs
     {
-      data: {
-        controller: "list"
-      }
+        data: { controller: "list" }
     }
   end
 
@@ -173,9 +175,24 @@ class List < Protos::Component
 end
 ```
 
-Attrs will by default merge `class` into the `css[:container]` slot so we
-changed that in our theme. We also added `default_attrs` and gave a controller.
-These could be any html options.
+`#attrs` will by default merge the `class` keyword into the `css[:container]`
+slot which we define in our theme.
+
+Special html options will be safely merged. For examples, the component above
+defines a list controller. If we passed our own controller into data when we
+initialize, the component's data-controller attribute would be appended to:
+
+```ruby
+render List.new(
+  data: { controller: "tooltip" }
+)
+```
+
+That would output both controllers to the DOM element:
+
+```html
+<ul data-controller="list tooltip">
+```
 
 If we wanted to, just like for our theme we can change the method from
 `default_attrs` by defining the `default_attrs_method` on the class:
@@ -184,37 +201,16 @@ If we wanted to, just like for our theme we can change the method from
 class List < Protos::Component
   default_attrs_method :custom_attrs
 
-  # ...
-
   private
 
   def custom_attrs
     {
-      data: {
-        controller: "list"
-      }
+      data: { controller: "list" }
     }
   end
-
-  # ...
 end
 ```
 
-Now we get some additional convenience:
-
-```ruby
-render List.new(
-  class: "my-lg",
-  data: { controller: "confetti" }
-)
-```
-
-This would merge our `data` and `class` safely into the attributes:
-
-```html
-<ul data-controller="list confetti" class="space-y-4 my-lg">
-```
-
 ### Params and options
 
 Components extend
@@ -242,7 +238,7 @@ Here is an example of a small navbar component:
 require "protos"
 
 class Navbar < Protos::Component
-  def template
+  def view_template
     # **attrs will add:
     # - Any html options defined on the component initialization such as data,
     #   role, for, etc..
@@ -379,11 +375,11 @@ import "protos-stimulus"
 Then you can use the components in your apps.
 
 ```ruby
-render Protos::Card.new(class: "bg-base-100") do |card|
-  render card.body(class: "gap-sm") do
-    render card.title(class: "font-bold") { "Hello world" }
+Protos::Card.new(class: "bg-base-100") do |card|
+  card.body(class: "gap-sm") do
+    card.title(class: "font-bold") { "Hello world" }
     span { "This is some more content" }
-    render card.actions do
+    card.actions do
       button(class: "btn btn-primary") { "Action 1" }
     end
   end
@@ -661,6 +657,25 @@ git commits and the created tag, and push the `.gem` file to
 Bug reports and pull requests are welcome on GitHub at
 https://github.com/inhouse-work/protos.
 
+## Benchmarks
+
+You can run the benchmarks using the raketasks, e.g:
+
+- `bin/rake benchmark:ips:table`
+- `bin/rake benchmark:memory:table`
+- `bin/rake benchmark:ips:theme`
+- `bin/rake benchmark:ips:attributes`
+
+There are also tasks for profiling and exploring memory consumption.
+
+You can find the latest benchmarks in `benchmarks/`.
+
+Currently this library is 30x slower than plain Phlex components. This is due to
+the overhead of themes, attributes and other quality of life improvements.
+
+This may seem like a lot but Phlex is so fast that rendering a large table can
+still be done 4000 times per second with this lib.
+
 ## License
 
 The gem is available as open source under the terms of the

data/benchmarks/table.txt

@@ -0,0 +1,12 @@
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
+Warming up --------------------------------------
+       Protos::Table    41.000 i/100ms
+        Phlex::Table     1.239k i/100ms
+Calculating -------------------------------------
+       Protos::Table    417.028 (± 0.2%) i/s -      2.091k in   5.014103s
+        Phlex::Table     12.785k (± 0.6%) i/s -     64.428k in   5.039702s
+
+Comparison:
+        Phlex::Table:    12784.6 i/s
+       Protos::Table:      417.0 i/s - 30.66x  slower
+

data/examples/list.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 require "protos"
 
 class List < Protos::Component
-  def template
+  def view_template
     ul(**attrs) do
       li(class: css[:item]) { "Item 1" }
       li(class: css[:item]) { "Item 2" }

data/examples/navbar.rb

@@ -3,7 +3,7 @@
 require_relative "../lib/protos"
 
 class Navbar < Protos::Component
-  def template
+  def view_template
     header(**attrs) do
       h1(class: css[:heading]) { "Hello world" }
       h2(class: css[:subtitle]) { "With a subtitle" }

data/lib/protos/accordion/item.rb

@@ -7,12 +7,12 @@ module Protos
 
       option :id, type: Types::Coercible::String
 
-      def template(&block)
+      def view_template(&block)
         li(**attrs) do
-          render collapse_component do
+          render Collapse.new(theme: collapse_theme) do
             # form: "" prevents the radio button from being submitted if its
             # within a form
-            input(type: :radio, name: id, form: "")
+            input(type: :radio, name: id, form: "", autocomplete: :off)
             yield if block
           end
         end
@@ -20,11 +20,10 @@ module Protos
 
       private
 
-      def collapse_component
-        collapse_theme = { "!container": tokens("bg-base-100") }
-        collapse_theme[:container!] = css[:collapse] if css[:collapse]
-
-        Collapse.new(theme: collapse_theme)
+      def collapse_theme
+        { "!container": tokens("bg-base-100") }.tap do |theme|
+          theme[:container!] = css[:collapse] if css[:collapse]
+        end
       end
 
       def theme

data/lib/protos/accordion.rb

@@ -10,20 +10,16 @@ module Protos
     option :id,
            default: -> { "collapse-#{SecureRandom.hex(4)}" }
 
-    def template(&block)
-      ul(**attrs, &block)
+    def view_template(&)
+      ul(**attrs, &)
     end
 
-    def item(**kwargs)
-      Item.new(id:, **kwargs)
-    end
+    def item(*, **, &) = render Item.new(*, id:, **, &)
 
-    def title(*args, **kwargs, &block)
-      Collapse::Title.new(*args, id:, **kwargs, &block)
-    end
+    def content(...) = render Collapse::Content.new(...)
 
-    def content(...)
-      Collapse::Content.new(...)
+    def title(*, **, &)
+      render Collapse::Title.new(*, id:, **, &)
     end
 
     private

data/lib/protos/alert/actions.rb

@@ -5,8 +5,8 @@ module Protos
     class Actions < Component
       # DOCS: Area for actions (e.g buttons) within an alert
 
-      def template(&block)
-        nav(**attrs, &block)
+      def view_template(&)
+        nav(**attrs, &)
       end
 
       private

data/lib/protos/alert/icon.rb

@@ -6,8 +6,8 @@ module Protos
       # DOCS: Icon for the alert, usually showing at the top left corner aligned
       # to the text
 
-      def template(&block)
-        div(**attrs, &block)
+      def view_template(&)
+        div(**attrs, &)
       end
 
       private

data/lib/protos/alert.rb

@@ -15,17 +15,13 @@ module Protos
 
     option :type, type: AlertTypes, default: -> { :info }, reader: :private
 
-    def template(&block)
-      div(**attrs, &block)
+    def view_template(&)
+      div(**attrs, &)
     end
 
-    def icon(...)
-      Icon.new(...)
-    end
+    def icon(...) = render Icon.new(...)
 
-    def actions(...)
-      Actions.new(...)
-    end
+    def actions(...) = render Actions.new(...)
 
     private
 

data/lib/protos/attributes.rb

@@ -11,7 +11,7 @@ module Protos
     # controllers do not get overridden.
 
     def initialize(attrs = {}, **kwargs)
-      @attrs = attrs.merge(kwargs)
+      @attrs = attrs.merge!(kwargs)
     end
 
     def [](key)
@@ -19,9 +19,10 @@ module Protos
     end
 
     def merge(hash)
-      tap do
-        @attrs = mix(@attrs, hash)
-      end
+      return self unless hash
+
+      @attrs = mix(@attrs, hash)
+      self
     end
 
     # Allows for the use of the `**` operator to pass the attributes to
@@ -32,10 +33,8 @@ module Protos
 
     private
 
-    def mix(*hashes)
-      hashes.each_with_object({}).each do |hash, result|
-        hash ||= {}
-
+    def mix(hash, *hashes)
+      hashes.each_with_object(hash) do |hash, result|
         result.merge!(hash) do |_key, a, b| # rubocop:disable Metrics/ParameterLists
           case [a, b]
           in String, String then "#{a} #{b}"

data/lib/protos/avatar.rb

@@ -17,7 +17,7 @@ module Protos
            default: -> { :none },
            reader: false
 
-    def template(&block)
+    def view_template(&block)
       div(**attrs) do
         div(class: css[:figure], &block)
       end

data/lib/protos/breadcrumbs/crumb.rb

@@ -5,8 +5,8 @@ module Protos
     class Crumb < Component
       # DOCS: A crumb is a single item within a breadcrumb
 
-      def template(&block)
-        li(**attrs, &block)
+      def view_template(&)
+        li(**attrs, &)
       end
     end
   end

data/lib/protos/breadcrumbs.rb

@@ -5,15 +5,13 @@ module Protos
     # DOCS: A list of breadcrumbs (e.g links) for navigation
     # https://daisyui.com/components/breadcrumbs/
 
-    def template(&block)
+    def view_template(&block)
       nav(**attrs) do
         ul(class: css[:list], &block)
       end
     end
 
-    def crumb(...)
-      Crumb.new(...)
-    end
+    def crumb(...) = render Crumb.new(...)
 
     private
 

data/lib/protos/card/actions.rb

@@ -5,8 +5,8 @@ module Protos
     class Actions < Component
       # DOCS: Area for actions (e.g buttons) within a card
 
-      def template(&block)
-        nav(**attrs, &block)
+      def view_template(&)
+        nav(**attrs, &)
       end
 
       private

data/lib/protos/card/body.rb

@@ -5,8 +5,8 @@ module Protos
     class Body < Component
       # DOCS: The main content area of a card
 
-      def template(&block)
-        div(**attrs, &block)
+      def view_template(&)
+        div(**attrs, &)
       end
 
       private

data/lib/protos/card/image.rb

@@ -7,8 +7,8 @@ module Protos
       # on daisyui which will style the <figure> tag depending on whether
       # image-overlay is present on the card.
 
-      def template(&block)
-        figure(**attrs, &block)
+      def view_template(&)
+        figure(**attrs, &)
       end
     end
   end

data/lib/protos/card/title.rb

@@ -5,8 +5,8 @@ module Protos
     class Title < Component
       # DOCS: The title of a card
 
-      def template(&block)
-        div(**attrs, &block)
+      def view_template(&)
+        div(**attrs, &)
       end
 
       private

data/lib/protos/card.rb

@@ -14,25 +14,17 @@ module Protos
            default: -> { :default },
            reader: false
 
-    def template(&block)
-      article(**attrs, &block)
+    def view_template(&)
+      article(**attrs, &)
     end
 
-    def body(...)
-      Body.new(...)
-    end
+    def body(...) = render Body.new(...)
 
-    def image(...)
-      Image.new(...)
-    end
+    def image(...) = render Image.new(...)
 
-    def title(...)
-      Title.new(...)
-    end
+    def title(...) = render Title.new(...)
 
-    def actions(...)
-      Actions.new(...)
-    end
+    def actions(...) = render Actions.new(...)
 
     private
 

data/lib/protos/carousel/actions.rb

@@ -5,8 +5,8 @@ module Protos
     class Actions < Component
       # DOCS: Area for actions (e.g buttons) within a carousel
 
-      def template(&block)
-        div(**attrs, &block)
+      def view_template(&)
+        div(**attrs, &)
       end
 
       private

data/lib/protos/carousel/item.rb

@@ -5,8 +5,8 @@ module Protos
     class Item < Component
       # DOCS: A single item within a carousel
 
-      def template(&block)
-        div(**attrs, &block)
+      def view_template(&)
+        div(**attrs, &)
       end
 
       private

data/lib/protos/carousel.rb

@@ -16,17 +16,13 @@ module Protos
              :end
            )
 
-    def template(&block)
-      div(**attrs, &block)
+    def view_template(&)
+      div(**attrs, &)
     end
 
-    def item(...)
-      Item.new(...)
-    end
+    def item(...) = render Item.new(...)
 
-    def actions(...)
-      Actions.new(...)
-    end
+    def actions(...) = render Actions.new(...)
 
     private
 

data/lib/protos/chat_bubble/content.rb

@@ -20,8 +20,8 @@ module Protos
                :error
              )
 
-      def template(&block)
-        div(**attrs, &block)
+      def view_template(&)
+        div(**attrs, &)
       end
 
       private

data/lib/protos/chat_bubble/footer.rb

@@ -5,8 +5,8 @@ module Protos
     class Footer < Component
       # DOCS: The footer of a chat bubble
 
-      def template(&block)
-        div(**attrs, &block)
+      def view_template(&)
+        div(**attrs, &)
       end
 
       private

data/lib/protos/chat_bubble/header.rb

@@ -6,8 +6,8 @@ module Protos
       # DOCS: The header of a chat bubble. This is typically used to display the
       # name of the user who sent the message.
 
-      def template(&block)
-        div(**attrs, &block)
+      def view_template(&)
+        div(**attrs, &)
       end
 
       private