protos 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5597289c15da1a04af0498dfcb056348db536a56920235d860a474766ffff1a
-  data.tar.gz: 87a9bbe792395f7060befc199de669ee7155d2889b995fbaf8a09961dc2aa65a
+  metadata.gz: 6771e623cc76042636663c199b9dd48e3b9d8ed5011d180f7e9e1fa50728fc65
+  data.tar.gz: 3dcd91f89719b72fbd9f23725add23ef09d0588196f8647ed7597baeed48b5de
 SHA512:
-  metadata.gz: 90d1beb6df64bce823af006a5c8c345756f54f5ae8907aebbbc593e00ebfad4873b1fa6ef60080ba645fd81a1e2466f0b1ff93127c5da1fccb7dd080511ebfbc
-  data.tar.gz: bed5be76a036311d146bcb0742fea11d15d52d0d4a23c5740929b270ebd86187cc79f6c804a2af6263e4c451651c6ddf6d578175a410f6d63161795d6b59384d
+  metadata.gz: 843780d369c551ee4e407037a6fa842343d36f9582d73823573af5bb06ee243424d85416737d9c6e80f433ab0147be41caf7af93b1c5db64765f479886157340
+  data.tar.gz: 37fb34135c07d53fc0d9e7af1c814f91130ed0a6891fb00db2059090fe7ec8787cebc004b41186a9cf09c936a151c9c2ef503333a25169cee91b1a3ca67f5864

data/README.md

@@ -11,99 +11,232 @@ You can see a full list of the components at
 [tailwind\_merge](https://github.com/gjtorikian/tailwind_merge).
 - Uses [tippy.js](https://atomiks.github.io/tippyjs/v6/getting-started/) for
   dropdowns, combobox, and popovers
+- All components avoid using
+  [`Phlex::DeferredRender`](https://www.phlex.fun/#slots)
+  so you can reorder components exactly how you like them.
 
 Other Phlex based UI libraries worth checking out:
 
 - [PhlexUI](https://phlexui.com/)
 - [ZestUI](https://zestui.com/)
 
-This library avoids re-making Protos components for extremely simple daisyui
-components such as:
+## Protos::Component
 
-- Badge
-- Buttons
-- Checkbox
-- File input
-- Indicator
-- Join
-- Kbd
-- Link
-- Loading
-- Mask
-- Progress
-- Radial progress
-- Radio
-- Range
-- Select
-- Skeleton
-- Stack
-- Text input
-- Textarea
-- Toggle
-- Tooltip
+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.
+
+We try and resolve this tensions by making the 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)
 
-All components avoid using
-[`Phlex::DeferredRender`](https://www.phlex.fun/#slots)
-so you can reorder components exactly how you like them.
+### Slots and themes
 
-Components are easy to style, positioning them is usually done through the
-`class` option which applies the style to the outer most container of the
-component:
+Components are styled with `css` slots that are filled with values from
+a `theme`:
 
 ```ruby
-render Protos::Avatar.new(class: "my-lg") do |avatar|
-  # ...
+class List < Protos::Component
+  def template
+    ul(class: css[:list]) do
+      li(class: css[:item]) { "Item 1" }
+      li(class: css[:item]) { "Item 2" }
+    end
+  end
+
+  def theme
+    {
+      list: tokens("space-y-4"),
+      item: tokens("font-bold", "text-2xl")
+    }
+  end
 end
 ```
 
-But they are also extensible to all styles by injecting a `theme` into the
-component:
+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
-render Protos::Avatar.new(theme: {
-    container: "my-lg",
-    figure: "p-sm" # Apply this padding to the image container
-}) do |avatar|
+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
 ```
 
-You can even override or negate certain parts of the theme:
+Using a theme and css slots allows us to easily override any part of a component
+when we render:
 
 ```ruby
-render Protos::Avatar.new(theme: {
-    container!: "my-lg", # Override the original container style
-    "!figure": "p-sm"    # Remove this class from the figure style
-}) do |avatar|
-  # ...
+render List.new(
+  theme: {
+    list: "space-y-8",
+    item: "bg-red-500"
+  }
+)
+```
+
+This would combine the default and our theme using tailwind\_merge:
+
+```html
+<ul class="space-y-8">
+  <li class="font-bold text-2xl bg-red-500">Item 1</li>
+  <li class="font-bold text-2xl bg-red-500">Item 2</li>
+</ul>
+```
+
+We can override the slot entirely by using a `!` at the end of the key:
+
+```ruby
+render List.new(
+  theme: {
+    item!: "bg-red-500"
+  }
+)
+```
+
+The css slot `css[:item]` would be overridden rather than merged:
+
+```html
+<li class="bg-red-500">Item 1</li>
+```
+
+We can also negate a certain class or classes from the slot by putting a `!` 
+at the start of the key:
+
+```ruby
+render List.new(
+  theme: {
+    "!item": "text-2xl"
+  }
+)
+```
+
+The new `css[:item]` slot would be:
+
+```html
+<li class="font-bold">Item 1</li>
+```
+
+### 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
+
+```ruby
+class List < Protos::Component
+  def template
+    ul(**attrs) do
+      # ...
+    end
+  end
+
+  private
+
+  def default_attrs
+    {
+      data: {
+        controller: "list"
+      }
+    }
+  end
+
+  def theme
+    {
+      container: tokens("space-y-4"),
+      item: tokens("font-bold")
+    }
+  end
 end
 ```
 
-If the component uses a stimulus controller on the data component, or any other
-default attributes you can safely add to them without overriding:
+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.
+
+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:
 
 ```ruby
-render Protos::Avatar.new(data: { controller: "my-controller" }) do |avatar|
+class List < Protos::Component
+  default_attrs_method :custom_attrs
+
   # ...
+
+  private
+
+  def custom_attrs
+    {
+      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
+[`Dry::Initializer`](https://dry-rb.org/gems/dry-initializer/3.1/)
+which lets us easily add new positional arguments with `param` or keyword
+arguments with `option`
+
+```ruby
+class List < Protos::Component
+  option :ordered
 end
 ```
 
-This will add your attributes without removing the important ones that help the
-components be accessible.
+The following keywords are reserved in the base class:
 
-Protos uses a set of conventions that make it easier to work with tailwindcss
-and components in Phlex which you can use in your own components by inheriting 
-from the base component.
+- `class`
+- `theme`
+- `html_options`
 
-This adds:
-1. extends `Dry::Initializer` to easily add initialization params and options
-2. adds `attrs` which merges html attributes onto defaults
-3. adds `default_attrs` for default html attributes on a component
-4. adds `theme` for default styles hash
-5. adds `css` for accessing theme slots
+## Putting it all together
 
-You can find this example in `examples/navbar.rb` which you can run with `ruby
-examples/navbar.rb`:
+Here is an example of a small navbar component:
 
 ```ruby
 require "protos"
@@ -179,10 +312,20 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-Setup tailwindcss to add the protos path to your content.
+Setup [Tailwindcss](https://tailwindcss.com/), [daisyUI](https://daisyui.com)
+and add the protos path to your content.
+
+```
+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
+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
-numbers so you can easily choose the spacing you want.
+numbers so you can easily choose the spacing you want. So we will need to extend
+`spacing` in your theme.
 
 ```js
 // tailwind.config.js
@@ -233,14 +376,14 @@ And somewhere in your entrypoints import as a side effect:
 import "protos-stimulus"
 ```
 
-Then you can use the components
+Then you can use the components in your apps.
 
 ```ruby
 render Protos::Card.new(class: "bg-base-100") do |card|
-  card.body(class: "gap-sm") do
-    card.title(class: "font-bold") { "Hello world" }
+  render card.body(class: "gap-sm") do
+    render card.title(class: "font-bold") { "Hello world" }
     span { "This is some more content" }
-    card.actions do
+    render card.actions do
       button(class: "btn btn-primary") { "Action 1" }
     end
   end
@@ -249,9 +392,31 @@ end
 
 ## Building your own components
 
-A good idea would be to encapsulate these proto components with your own
-components as a wrapper. For example you could use `Proto::List` to create your
-own list and even use `Phlex::DeferredRender` to make the API more convenient.
+You can override components simply by redefining the class in your own app:
+
+```ruby
+module Protos
+  class Swap < Component
+    private
+
+    def on(...)
+      MyOnButton.new(...)
+    end
+
+    def theme
+      super.merge({
+        input: tokens("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
+`Phlex::DeferredRender` to make the API more convenient.
+
+Let's create a list component with headers and actions:
 
 ```ruby
 module Ui
@@ -314,9 +479,9 @@ Now the component is specific to our application, and the styles are still
 overridable at all levels:
 
 ```ruby
-render Ui::List.new(title: "Project Names") do |list|
+render Ui::List.new(title: "Project Names", ordered: true) do |list|
   list.with_action { link_to("Add item", "#") }
-  list.with_item { "Project 1" }
+  list.with_item(class: "active") { "Project 1" }
   list.with_item { "Project 2" }
   list.with_item { "Project 3" }
 end
@@ -452,6 +617,33 @@ render Ui::Table.new(title: "A table", collection:) do |table|
 end
 ```
 
+## No unnecessary components
+
+This library avoids re-making Protos components for extremely simple daisyui
+components such as:
+
+- Badge
+- Buttons
+- Checkbox
+- File input
+- Indicator
+- Join
+- Kbd
+- Link
+- Loading
+- Mask
+- Progress
+- Radial progress
+- Radio
+- Range
+- Select
+- Skeleton
+- Stack
+- Text input
+- Textarea
+- Toggle
+- Tooltip
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/examples/list.rb

@@ -0,0 +1,34 @@
+require "protos"
+
+class List < Protos::Component
+  def template
+    ul(**attrs) do
+      li(class: css[:item]) { "Item 1" }
+      li(class: css[:item]) { "Item 2" }
+    end
+  end
+
+  def default_attrs
+    {
+      data: {
+        controller: "list"
+      }
+    }
+  end
+
+  def theme
+    {
+      container: tokens("space-y-4"),
+      item: tokens("font-bold")
+    }
+  end
+end
+
+list = List.new(
+  theme: {
+    container: "space-y-8",
+    item: "bg-red-500"
+  }
+)
+
+puts list.call

data/lib/protos/accordion/item.rb

@@ -3,11 +3,13 @@
 module Protos
   class Accordion
     class Item < Component
+      # DOCS: An accorion is just a collapse with radio buttons.
+
       option :id, type: Types::Coercible::String
 
       def template(&block)
         li(**attrs) do
-          render collapse do |_collapse|
+          render collapse_component do
             input(type: :radio, name: id, id:)
             yield if block
           end
@@ -16,11 +18,11 @@ module Protos
 
       private
 
-      def collapse
+      def collapse_component
         collapse_theme = { "!container": tokens("bg-base-100") }
-        collapse_theme[:container!] = css[:collapse]
+        collapse_theme[:container!] = css[:collapse] if css[:collapse]
 
-        Collapse.new(theme: collapse_theme.compact)
+        Collapse.new(theme: collapse_theme)
       end
 
       def theme

data/lib/protos/accordion.rb

@@ -2,6 +2,11 @@
 
 module Protos
   class Accordion < Component
+    # DOCS: The accordion component. Accordion is a collapse with radio buttons.
+    # Only one item can be open at a time. If you want to allow multiple items
+    # to be open at the same time, use the collapse component.
+    # https://daisyui.com/components/accordion/
+
     option :id, default: -> { SecureRandom.uuid }
 
     def template(&block)

data/lib/protos/alert/actions.rb

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

data/lib/protos/alert/icon.rb

@@ -3,6 +3,9 @@
 module Protos
   class Alert
     class Icon < Component
+      # DOCS: Icon for the alert, usually showing at the top left corner aligned
+      # to the text
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/alert.rb

@@ -2,6 +2,10 @@
 
 module Protos
   class Alert < Component
+    # DOCS: A component that displays messages (usually from flashes). These can
+    # be used in combination with Protos::Toast to have popup notifications.
+    # https://daisyui.com/components/alert/
+
     AlertTypes = Types::Coercible::Symbol.enum(
       :info,
       :success,

data/lib/protos/attributes.rb

@@ -2,6 +2,14 @@
 
 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)
     end

data/lib/protos/avatar.rb

@@ -2,6 +2,9 @@
 
 module Protos
   class Avatar < Component
+    # DOCS: The avatar component is used to represent a user or entity.
+    # https://daisyui.com/components/avatar/
+
     IndicatorTypes = Types::Coercible::Symbol.enum(:none, :online, :offline)
 
     option :placeholder, type: Types::Bool, default: -> { false }

data/lib/protos/breadcrumbs/crumb.rb

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

data/lib/protos/breadcrumbs.rb

@@ -2,6 +2,9 @@
 
 module Protos
   class Breadcrumbs < Component
+    # DOCS: A list of breadcrumbs (e.g links) for navigation
+    # https://daisyui.com/components/breadcrumbs/
+
     def template(&block)
       nav(**attrs) do
         ul(class: css[:list], &block)

data/lib/protos/card/actions.rb

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

data/lib/protos/card/body.rb

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

data/lib/protos/card/image.rb

@@ -3,6 +3,10 @@
 module Protos
   class Card
     class Image < Component
+      # DOCS: A container for an image for on a card. This matches the examples
+      # on daisyui which will style the <figure> tag depending on whether
+      # image-overlay is present on the card.
+
       def template(&block)
         figure(**attrs, &block)
       end

data/lib/protos/card/title.rb

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

data/lib/protos/card.rb

@@ -2,6 +2,9 @@
 
 module Protos
   class Card < Component
+    # DOCS: A card component
+    # https://daisyui.com/components/card/
+
     ImageDisplayTypes = Types::Coercible::Symbol.enum(:default, :overlay, :side)
 
     option :border, type: Types::Bool, default: -> { true }, reader: :private

data/lib/protos/carousel/actions.rb

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

data/lib/protos/carousel/item.rb

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

data/lib/protos/carousel.rb

@@ -2,6 +2,10 @@
 
 module Protos
   class Carousel < Component
+    # DOCS: A carousel component that contains items that can be scrolled
+    # through in a mobile friendly manner.
+    # https://daisyui.com/components/carousel/
+
     option :vertical, type: Types::Bool, default: -> { false }
     option :snap_to,
            default: -> { :none },

data/lib/protos/chat_bubble/content.rb

@@ -3,6 +3,9 @@
 module Protos
   class ChatBubble
     class Content < Component
+      # DOCS: The main content of a chat bubble. This would normally be the text
+      # content of the message. It will be colored according to the type.
+
       option :type,
              default: -> { :none },
              reader: false,