protos 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 875e55f36d03988e78d0e6834e840094b089ee1e755c003b6483a07a503bfbf4
-  data.tar.gz: 6b0bdbfc22451928316c73dd931cdeebe3e47cf20c596b3d5318b3145f51b5bc
+  metadata.gz: d7486060db2b247fab3e5d5caa33c6f8d35631772e267ae248d8929b71038fbb
+  data.tar.gz: ef414faf4cc381245bc9e7b609124858b4a1d1280dfcf5e21a139641d6877f0a
 SHA512:
-  metadata.gz: 62c59568bcf8631d3d9c40de57ddb6b1df2f92183c0e9aa92e8be6b0da7d6e325e440a869eda3f1fd0cb93f651f9db8598a9914cc89b6454a1cda7f5a04517fc
-  data.tar.gz: 2ef45fba8e402133e4345fa91186713dc864e11d737bf3200548340cf7ed3d115e08b406b6d5c98eab8d568d4178b37d1b5e43fa13569dcc873fda6a8f338be9
+  metadata.gz: 37c65c3a6be4bfc15fb70e31988a4624c56426e607796de03ae8be9b47be9f016ad27ee4fc508ec57442f6cb0ae8d5d2e27bad40b8b8178c61488935fcafbf9c
+  data.tar.gz: 56354393cb9425b3455bcf4baa568a7f23805a226a3b0de75264f505dc9c5f2deee503d77e4b3fd0d7e3ecdef6253daebc5262ba0cb5b7591b6582fec3f96adb

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+- Changes passing an `input_id` to accordions. Replaced with the more accurate
+  `input_name` (optional) parameter. There was no point in having different
+  name attributes for the different radio buttons
+- Updates modal component to use newer modal controller from protos-stimulus
+  that uses `@stimulus-components/dialog`
+- Adds the ability for `css` helper to take multiple values, including inline
+  values instead of theme keys.
+- Adds new `Protos::Badge` component
+- Removes deprecated tokens to prepare for phlex 2.0
+- Removes `dry-initializer` undefined constant to improve performance
+- Adds autoloading constants instead of hard requires
+
+## [0.6.0] - 2024-09-04
+
+- Changes how merging attributes works to only mix on certain attributes,
+  overriding on all others. This is opposite to how attributes used to be merged
+  by default. This is a fix for attributes like `value` where you actually need
+  to override them.
+- Adds a separate tested `Mix` class for handling attribute merging
+
 ## [0.5.0] - 2024-08-27
 
 - Fixes all accessibility violations according to Axe Core

data/README.md

@@ -20,10 +20,91 @@ Other Phlex based UI libraries worth checking out:
 - [PhlexUI](https://phlexui.com/)
 - [ZestUI](https://zestui.com/)
 
+Thinking of making your next static site using Phlex? Check out
+[staticky](https://github.com/nolantait/staticky). The protos docs were
+published using it.
+
+## Phlex components
+
+Phlex is a fantastic framework for building frontend components in pure Ruby:
+
+```ruby
+class Navbar
+  def view_template
+    header(class: "flex items-center justify-between") do
+      h3 { "My site" }
+      button { "Log out" }
+    end
+  end
+end
+```
+
+But how can we sometimes render this `Navbar` with a different background color?
+
+It would be nice to have our components take a class like any other element:
+
+```ruby
+render Navbar.new(class: "bg-primary")
+```
+
+Unfortunately `class` is a special keyword in Ruby, so we need to do some
+awkward handling to use it like this:
+
+```ruby
+class Navbar
+  def initialize(**options)
+    # Keyword `class` is a special word in Ruby so we have to awkwardly unwrap
+    # like this instead of using keyword arguments
+    @classes = options[:class]
+  end
+
+  def view_template
+    header(class: "#{@classes} flex items-center justify-between") do
+      h3 { "My site" }
+      button { "Log out" }
+    end
+  end
+end
+```
+
+Now we can pass in a style to our container, but what about overriding the style
+of the `h3` tag?
+
+```ruby
+class Navbar
+  def initialize(**options)
+    # Keyword `class` is a special word in Ruby so we have to awkwardly unwrap
+    # like this instead of using keyword arguments
+    @container_classes = options[:class]
+    @title_classes = options[:title_class]
+  end
+
+  def view_template
+    header(class: "#{@classes} flex items-center justify-between") do
+      h3(class: @title_classes) { "My site" }
+      button { "Log out" }
+    end
+  end
+end
+```
+
+Eventually everyone makes a kind of ad-hoc system for specifying styles.
+
+It gets more complicated when you have attributes like a data-controller. How do
+you give a good experience letting people using your components to add their own
+controllers while your component depends on one already?
+
+This library is an attempt to make this kind of developer experience while
+making reusable components more convention over configuration.
+
 ## Protos::Component
 
-A protos component follows some conventions that make them easy to work with as
-components in your app.
+A protos component follows 3 conventions that make them easy to work with as
+components in your app:
+
+- [Slots and themes](#slots-and-themes)
+- [Attrs and default attrs](#attrs-and-default-attrs)
+- [Params and options](#params-and-options)
 
 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
@@ -32,20 +113,18 @@ the box can make them hard to customize.
 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:
-- [Slots and themes](#slots-and-themes)
-- [Attrs and default attrs](#attrs-and-default-attrs)
-- [Params and options](#params-and-options)
-
 ### Slots and themes
 
-Components are styled with `css` slots that are filled with values from
-a `theme`.
+Components are styled with `css` slots that get their values from a simple hash
+we call a `theme`.
+
+You define a `theme` for your component by defining a `#theme` method that
+returns a hash.
+
+Users of your components can override, merge, or remove parts of your theme by
+passing in their own as an argument to the component. Another nice benefit is
+that your markup doesn't get overwhelmed horizontally with your css classes.
 
-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
@@ -58,7 +137,7 @@ class List < Protos::Component
 
   def theme
     {
-      list: tokens("space-y-4"), # We can use `#tokens` from phlex (recommended)
+      list: ["space-y-4"], # We can use arrays
       item: "font-bold text-2xl" # Or just plain old strings
     }
   end
@@ -66,7 +145,10 @@ end
 ```
 
 Using a theme and css slots allows us to easily override any part of a component
-when we render:
+when we render.
+
+Here we are passing in our own theme. The default behavior is to add these
+styles on to the theme, rather than replacing them.
 
 ```ruby
 render List.new(
@@ -77,7 +159,12 @@ render List.new(
 )
 ```
 
-This would combine the default and our theme using tailwind\_merge:
+When the component is rendered the `tailwind_merge` gem will also prune any
+duplicate unneeded styles.
+
+For example even though the themes `list` key would be added together to become
+`space-y-4 space-y-8`, the `tailwind_merge` gem will prune it down to just
+`space-y-8` as the two styles conflict.
 
 ```html
 <ul class="space-y-8">
@@ -119,8 +206,8 @@ 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:
+If you want to change the method we define our default theme under you can
+override the `theme_method` on the class:
 
 ```ruby
 class List < Protos::Component
@@ -132,22 +219,37 @@ class List < Protos::Component
 
   def custom_theme
     {
-      list: tokens("space-y-4"),
-      item: tokens("font-bold", "text-2xl")
+      list: "space-y-4",
+      item: ["font-bold", "text-2xl"]
     }
   end
 end
 ```
 
+Slots can also take multiple arguments, and even inline styles:
+
+```ruby
+class ListItem < Protos::Component
+  def view_template
+    li(class: css[:item, :primary_item, "text-sm"])
+  end
+end
+```
+
+This combines the styles together, removing any duplicates.
+
 ### Attrs and default attrs
 
 By convention, all components spread in an `attrs` hash on their outermost
-element of the component.
+element of the component. There is no rule for this, but it makes them feel more
+naturally like native html elements when you render them.
 
-By doing this we enable 2 main conveniences:
+By doing this we enable 3 main conveniences:
 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
+2. We can pass any html attributes we want to the element such as `id`, `data`
+   etc and it will just work
+3. We can add default attributes that are safely merged with any provided to the
    component when its being initialized
 
 ```ruby
@@ -168,19 +270,22 @@ class List < Protos::Component
 
   def theme
     {
-      container: tokens("space-y-4"),
-      item: tokens("font-bold")
+      container: "space-y-4",
+      item: "font-bold"
     }
   end
 end
 ```
 
-`#attrs` will by default merge the `class` keyword into the `css[:container]`
-slot which we define in our theme.
+`#attrs` returns a hash which will by default merge the `class` keyword into the
+`css[:container]` slot which we define in our theme. The `ul` elements class
+would be `space-y-4` as that is the `css[:container]` on our theme.
+
+Special html options (`class`, `data`) will be safely merged. 
 
-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:
+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(
@@ -194,6 +299,9 @@ That would output both controllers to the DOM element:
 <ul data-controller="list tooltip">
 ```
 
+This makes it very convenient to add functionality to basic components without
+overriding their core behavior or having to modify/override their class.
+
 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:
 
@@ -224,25 +332,27 @@ class List < Protos::Component
 end
 ```
 
+This makes our initialization declarative and easy to extend without having to
+consider how to call `super` in the initializer.
+
 The following keywords are reserved in the base class:
 
 - `class`
 - `theme`
 - `html_options`
 
+You are free to add whatever positional or keyword arguments you like as long as
+they don't directly conflict with those names.
+
 ## Putting it all together
 
-Here is an example of a small navbar component:
+Lets revisit the example of our `Navbar` component:
 
 ```ruby
 require "protos"
 
 class Navbar < Protos::Component
   def view_template
-    # **attrs will add:
-    # - Any html options defined on the component initialization such as data,
-    #   role, for, etc..
-    # - Class will be added to the css[:container] and applied
     header(**attrs) do
       h1(class: css[:heading]) { "Hello world" }
       h2(class: css[:subtitle]) { "With a subtitle" }
@@ -259,19 +369,19 @@ class Navbar < Protos::Component
 
   def theme
     {
-      container: tokens(
-        "flex",
-        "justify-between",
-        "items-center",
-        "gap-sm"
-      ),
-      heading: tokens("text-2xl", "font-bold"),
-      subtitle: tokens("text-base")
+      container: "flex justify-between items-center gap-sm",
+      heading: "text-2xl font-bold",
+      subtitle: "text-sm"
     }
   end
 end
+```
+
+Now all the concerns about adding in our behavior, styles, etc are handled for
+us by convention:
 
-component = Navbar.new(
+```ruby
+render Navbar.new(
   # This will add to the component's css[:container] slot
   class: "my-sm",
   # This will add the controller and not remove
@@ -283,8 +393,6 @@ component = Navbar.new(
     subtitle!: "text-xl"   # We can override the entire slot
   }
 )
-
-puts component.call
 ```
 
 Which produces the following html:
@@ -308,7 +416,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-Setup [Tailwindcss](https://tailwindcss.com/), [daisyUI](https://daisyui.com)
+Setup [TailwindCSS](https://tailwindcss.com/), [DaisyUI](https://daisyui.com)
 and add the protos path to your content.
 
 ```
@@ -316,7 +424,7 @@ npm install -D tailwindcss postcss autoprefixer daisyui
 npx tailwindcss init
 ```
 
-Then we need to add the protos path to the `content` of our tailwindcss config
+Then we need to add the protos path to the `content` of our tailwind config
 so tailwind will read the styles defined in the Protos gem.
 
 Protos also uses semantic spacing such as `p-sm` or `m-md` instead of set
@@ -344,15 +452,6 @@ module.exports = {
         lg: "var(--spacing-lg)",
         xl: "var(--spacing-xl)",
       },
-      // If you use % based spacing you might want different spacing
-      // for any vertical gaps to prevent overflow
-      gap: {
-        xs: "var(--spacing-gap-xs)",
-        sm: "var(--spacing-gap-sm)",
-        md: "var(--spacing-gap-md)",
-        lg: "var(--spacing-gap-lg)",
-        xl: "var(--spacing-gap-xl)",
-      },
     },
   }
   // ....
@@ -388,11 +487,12 @@ end
 
 ## Building your own components
 
-You can override components simply by redefining the class in your own app:
+You can override components simply by redefining sub-classing the class in your
+own app:
 
 ```ruby
-module Protos
-  class Swap < Component
+module Components
+  class Swap < Protos::Component
     private
 
     def on(...)
@@ -401,15 +501,29 @@ module Protos
 
     def theme
       super.merge({
-        input: tokens("block", "bg-red-500")
+        input: ["block", "bg-red-500"]
       })
     end
   end
 end
 ```
 
-You could also encapsulate these more primitive proto components into your own
-components. You could use `Proto::List` to create your own list and even use
+But its much better to avoid the sub-classing and just render the component
+inside of your own:
+
+```ruby
+module Components
+  class Swap < ApplicationComponent
+    def view_template
+      render Protos::Swap.new do |c|
+        # ....
+      end
+    end
+  end
+end
+```
+
+You could use `Proto::List` to create your own list and even use
 `Phlex::DeferredRender` to make the API more convenient.
 
 Let's create a list component with headers and actions:
@@ -460,11 +574,11 @@ module Ui
 
     def theme
       {
-        container: tokens("space-y-xs"),
-        header: tokens("flex", "justify-between", "items-end", "gap-sm"),
-        list: tokens("divide-y", "border", "w-full"),
-        actions: tokens("space-x-xs"),
-        item: tokens("p-sm")
+        container: "space-y-xs",
+        header: "flex justify-between items-end gap-sm",
+        list: "divide-y border w-full",
+        actions: "space-x-xs",
+        item: "p-sm"
       }
     end
   end
@@ -575,10 +689,10 @@ module Ui
 
     def theme
       {
-        container: tokens("space-y-sm"),
-        header: tokens("flex", "justify-between", "items-end", "gap-sm"),
-        table: tokens("border"),
-        caption: tokens("text-muted")
+        container: "space-y-sm",
+        header: "flex justify-between items-end gap-sm",
+        table: "border",
+        caption: "text-muted"
       }
     end
   end
@@ -613,12 +727,11 @@ render Ui::Table.new(title: "A table", collection:) do |table|
 end
 ```
 
-## No unnecessary components
+## Missing components
 
-This library avoids re-making Protos components for extremely simple daisyui
-components such as:
+This library tries to avoid re-making Protos components for extremely simple
+DaisyUI components. Here is a list that we don't yet have components for:
 
-- Badge
 - Buttons
 - Checkbox
 - File input

data/examples/list.rb

@@ -20,8 +20,8 @@ class List < Protos::Component
 
   def theme
     {
-      container: tokens("space-y-4"),
-      item: tokens("font-bold")
+      container: "space-y-4",
+      item: "font-bold"
     }
   end
 end

data/examples/navbar.rb

@@ -20,14 +20,9 @@ class Navbar < Protos::Component
 
   def theme
     {
-      container: tokens(
-        "flex",
-        "justify-between",
-        "items-center",
-        "gap-sm"
-      ),
-      heading: tokens("text-2xl", "font-bold"),
-      subtitle: tokens("text-base")
+      container: "flex justify-between items-center gap-sm",
+      heading: "text-2xl font-bold",
+      subtitle: "text-base"
     }
   end
 end

data/lib/protos/accordion/item.rb

@@ -5,13 +5,15 @@ module Protos
     class Item < Component
       # DOCS: An accorion is just a collapse with radio buttons.
 
-      option :input_id, type: Types::String | Types::Integer
+      option :input_name,
+        type: Types::String | Types::Integer | Types::Nil,
+        reader: false
 
       def view_template(&block)
         li(**attrs) do
           render Collapse.new(
             theme: collapse_theme,
-            input_id: @input_id.to_s,
+            input_name: @input_name,
             input_type: :radio,
             &block
           )

data/lib/protos/accordion.rb

@@ -7,30 +7,29 @@ module Protos
     # to be open at the same time, use the collapse component.
     # https://daisyui.com/components/accordion/
 
+    autoload :Item, "protos/accordion/item"
+
+    option :input_name,
+      default: -> { "accordion-#{SecureRandom.hex(4)}" },
+      reader: false,
+      type: Types::String
+
     def view_template(&)
       ul(**attrs, &)
     end
 
-    def item(*, input_id: nil, **, &)
-      self.current_input_id = input_id
-
-      render Item.new(*, input_id: current_input_id, **, &)
+    def item(*, **, &)
+      render Item.new(*, input_name: @input_name, **, &)
     end
 
     def content(...) = render Collapse::Content.new(...)
 
     def title(*, **, &)
-      render Collapse::Title.new(*, input_id: current_input_id, **, &)
+      render Collapse::Title.new(*, input_id: @input_name, **, &)
     end
 
     private
 
-    attr_reader :current_input_id
-
-    def current_input_id=(value)
-      @current_input_id = value || "collapse-#{SecureRandom.hex(4)}"
-    end
-
     def theme
       {
         container: "join join-vertical"

data/lib/protos/alert.rb

@@ -6,6 +6,9 @@ module Protos
     # be used in combination with Protos::Toast to have popup notifications.
     # https://daisyui.com/components/alert/
 
+    autoload :Actions, "protos/alert/actions"
+    autoload :Icon, "protos/alert/icon"
+
     Styles = Types::Coercible::Symbol.enum(
       :info,
       :success,

data/lib/protos/attributes.rb

@@ -4,11 +4,6 @@ module Protos
   class Attributes
     # DOCS: A class that represents the attributes of a component. This would be
     # all html options except for `class` and `theme`.
-    #
-    # This class is responsible for safely merging in both user supplied and
-    # default attributes. When a user adds { data: { controller: "foo" }} to
-    # their component. This will merge the value in so that any default
-    # controllers do not get overridden.
 
     def initialize(attrs = {}, **kwargs)
       @attrs = attrs.merge!(kwargs)
@@ -34,19 +29,7 @@ module Protos
     private
 
     def mix(hash, *hashes)
-      hashes.each_with_object(hash) do |hash, result|
-        result.merge!(hash) do |_key, a, b| # rubocop:disable Metrics/ParameterLists
-          next a unless b
-          next a if a == b
-
-          case [a, b]
-          in String, String then "#{a} #{b}"
-          in Array, Array then a + b
-          in Hash, Hash then mix(a, b)
-          else b
-          end
-        end
-      end
+      Mix.call(hash, *hashes)
     end
   end
 end

data/lib/protos/avatar.rb

@@ -64,13 +64,13 @@ module Protos
 
     option :placeholder, type: Types::Bool, default: -> { false }
     option :indicator,
-           type: Indicators,
-           default: -> { :none },
-           reader: false
+      type: Indicators,
+      default: -> { :none },
+      reader: false
     option :shape,
-           type: MaskShapes,
-           default: -> { :none },
-           reader: false
+      type: MaskShapes,
+      default: -> { :none },
+      reader: false
 
     def view_template(&block)
       div(**attrs) do
@@ -90,12 +90,12 @@ module Protos
 
     def theme
       {
-        container: tokens(
+        container: [
           "avatar",
           indicator,
-          placeholder: "placeholder"
-        ),
-        figure: tokens(shape)
+          ("placeholder" if placeholder)
+        ],
+        figure: shape
       }
     end
   end