protos 0.2.1 → 0.2.2

data/lib/protos/chat_bubble/footer.rb

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

data/lib/protos/chat_bubble/header.rb

@@ -3,6 +3,9 @@
 module Protos
   class ChatBubble
     class Header < Component
+      # 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)
       end

data/lib/protos/chat_bubble/image.rb

@@ -3,6 +3,9 @@
 module Protos
   class ChatBubble
     class Image < Component
+      # DOCS: An image within a chat bubble. This would typically be an avatar
+      # component.
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/chat_bubble.rb

@@ -2,6 +2,11 @@
 
 module Protos
   class ChatBubble < Component
+    # DOCS: A chat bubble component that contains a message an possibly some
+    # metadata and an image. Each chat bubble would represent a single message
+    # in a larger chat history.
+    # https://daisyui.com/components/chat/
+
     option :align,
            default: -> { :start },
            reader: false,

data/lib/protos/collapse/content.rb

@@ -3,6 +3,9 @@
 module Protos
   class Collapse
     class Content < Component
+      # DOCS: The content of a collapse. This would be hidden until the collapse
+      # is opened.
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/collapse/title.rb

@@ -3,6 +3,9 @@
 module Protos
   class Collapse
     class Title < Component
+      # DOCS: The title of a collapse. This is the content that is always
+      # visible and is used to toggle the collapse.
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/collapse.rb

@@ -2,6 +2,10 @@
 
 module Protos
   class Collapse < Component
+    # DOCS: A collapsible container that can be expanded or collapsed. The title
+    # is visible at all times, and the content is only visible when expanded.
+    # https://daisyui.com/components/collapse/
+
     def template(&block)
       div(**attrs, &block)
     end

data/lib/protos/combobox.rb

@@ -2,6 +2,10 @@
 
 module Protos
   class Combobox < Popover
+    # DOCS: A combobox is a combination of a text input and a list of options.
+    # It makes selecting values from a large list easier by filtering the list.
+    # Comboboxes use popovers and command to create the list of options.
+
     option :trigger,
            default: -> { :click },
            reader: false,

data/lib/protos/command/dialog.rb

@@ -3,6 +3,9 @@
 module Protos
   class Command
     class Dialog < Component
+      # DOCS: The dialog for a command wraps the command content and provides a
+      # modal backdrop for the command when it is opened.
+
       def template(&block)
         dialog(**attrs) do
           div(class: css[:modal], &block)
@@ -22,7 +25,12 @@ module Protos
 
       def theme
         {
-          container: tokens("modal", "modal-bottom", "sm:modal-middle"),
+          container: tokens(
+            "modal",
+            "modal-bottom",
+            "backdrop-blur-sm",
+            "sm:modal-middle"
+          ),
           modal: tokens("modal-box", "p-0"),
           form: tokens("modal-backdrop")
         }

data/lib/protos/command/empty.rb

@@ -3,6 +3,9 @@
 module Protos
   class Command
     class Empty < Component
+      # DOCS: The empty component is displayed in the list when there are no
+      # matches in an input.
+
       def template(&block)
         li(**attrs, &block)
       end

data/lib/protos/command/group.rb

@@ -3,6 +3,10 @@
 module Protos
   class Command
     class Group < Component
+      # DOCS: An optional group for holding a heading and a list of options.
+      # Items in the group will have a divider line on the left side and can
+      # optionally have a title.
+
       def template(&block)
         li(**attrs) do
           ul(class: css[:list], &block)

data/lib/protos/command/input.rb

@@ -3,6 +3,8 @@
 module Protos
   class Command
     class Input < Component
+      # DOCS: The search input for the command palette
+
       option :placeholder,
              default: -> {
                "Type a command or search..."

data/lib/protos/command/item.rb

@@ -3,6 +3,8 @@
 module Protos
   class Command
     class Item < Component
+      # DOCS: A single option within a command
+
       def template(&block)
         li(**attrs, &block)
       end

data/lib/protos/command/list.rb

@@ -3,6 +3,8 @@
 module Protos
   class Command
     class List < Component
+      # DOCS: A list of commands. This can contain either items or groups.
+
       def template(&block)
         ul(**attrs, &block)
       end

data/lib/protos/command/title.rb

@@ -3,6 +3,9 @@
 module Protos
   class Command
     class Title < Component
+      # DOCS: The title for a group of commands. This is expected to be used
+      # inside a Protos::Command::Group component.
+
       def template(&block)
         h2(**attrs, &block)
       end

data/lib/protos/command/trigger.rb

@@ -3,6 +3,8 @@
 module Protos
   class Command
     class Trigger < Component
+      # DOCS: A trigger is a button that opens a command palette modal
+
       def template(&block)
         button(**attrs, &block)
       end

data/lib/protos/command.rb

@@ -2,6 +2,10 @@
 
 module Protos
   class Command < Component
+    # DOCS: A command pallete component that can be used to trigger a modal with
+    # filterable list of commands. Command modals are by default closable by
+    # clicking the overlay rather than a specific close button.
+
     def template(&block)
       div(**attrs, &block)
     end

data/lib/protos/component.rb

@@ -2,17 +2,23 @@
 
 module Protos
   class Component < Phlex::HTML
-    # DOCS: Base component
+    # DOCS: Base component for all Protos::Components. You can inherit from this
+    # class to gain flexible components you can style from the outside using css
+    # slots, default attrs and themes.
+    #
+    # This component extends Dry::Initializer and Dry::Core::ClassAttributes to
+    # make configuring each class much easier. It also enables gathering up all
+    # undefined options and adding them to the html_options hash.
 
     extend Dry::Initializer
     extend Dry::Core::ClassAttributes
 
     # Define methods for css and attrs. Each is expected to return a hash
-    defines :css_method, type: Types::Symbol
-    defines :attrs_method, type: Types::Symbol
+    defines :theme_method, type: Types::Symbol
+    defines :default_attrs_method, type: Types::Symbol
 
-    css_method :theme
-    attrs_method :default_attrs
+    theme_method :theme
+    default_attrs_method :default_attrs
 
     # Theme can override the css hash and add additional styles
     option :theme, as: :theme_override, default: -> { {} }, reader: :private
@@ -53,8 +59,11 @@ module Protos
     end
 
     def build_attrs(...)
-      defaults = if respond_to?(self.class.attrs_method, :include_private)
-        send(self.class.attrs_method)
+      defaults = if respond_to?(
+        self.class.default_attrs_method,
+        :include_private
+      )
+        send(self.class.default_attrs_method)
       end
 
       Attributes
@@ -65,8 +74,11 @@ module Protos
     end
 
     def build_theme(...)
-      component_style = if respond_to?(self.class.css_method, :include_private)
-        send(self.class.css_method)
+      component_style = if respond_to?(
+        self.class.theme_method,
+        :include_private
+      )
+        send(self.class.theme_method)
       end
 
       Theme

data/lib/protos/drawer/content.rb

@@ -3,6 +3,9 @@
 module Protos
   class Drawer
     class Content < Component
+      # DOCS: The content of a drawer. This would be visible at all times and
+      # represents the main content of your page.
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/drawer/side.rb

@@ -3,6 +3,9 @@
 module Protos
   class Drawer
     class Side < Component
+      # DOCS: The content that will be shown when you open the drawer using the
+      # trigger. This would be hidden until triggered.
+
       option :id, type: Types::Coercible::String
 
       def template
@@ -16,7 +19,11 @@ module Protos
 
       def theme
         {
-          container: tokens("drawer-side", "z-20"),
+          container: tokens(
+            "drawer-side",
+            "z-20",
+            "peer-checked:backdrop-blur-sm"
+          ),
           toggle: tokens("drawer-overlay")
         }
       end

data/lib/protos/drawer/trigger.rb

@@ -3,6 +3,9 @@
 module Protos
   class Drawer
     class Trigger < Component
+      # DOCS: The trigger for a drawer. When this is clicked the side will open
+      # and overlap the main content with a darker overlay.
+
       option :id, type: Types::Coercible::String
 
       def template(&block)

data/lib/protos/drawer.rb

@@ -2,6 +2,11 @@
 
 module Protos
   class Drawer < Component
+    # DOCS: A drawer component that can be toggled via a trigger. The content of
+    # a drawer is displayed at all times and overlapped by the side when the
+    # trigger is clicked.
+    # https://daisyui.com/components/drawer/
+
     option :id, type: Types::Coercible::String
 
     def template
@@ -28,7 +33,7 @@ module Protos
     def theme
       {
         container: tokens("drawer"),
-        toggle: tokens("drawer-toggle")
+        toggle: tokens("drawer-toggle", "peer")
       }
     end
   end

data/lib/protos/dropdown/item.rb

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

data/lib/protos/dropdown/menu.rb

@@ -3,6 +3,10 @@
 module Protos
   class Dropdown
     class Menu < Popover::Content
+      # DOCS: The container for items in a dropdown. This is a restyled
+      # Protos::Popover::Content component as the main functionality for
+      # dropdowns comes from there.
+
       def template(&block)
         template_tag(**template_attrs) do
           ul(**attrs, &block)

data/lib/protos/dropdown/trigger.rb

@@ -3,6 +3,8 @@
 module Protos
   class Dropdown
     class Trigger < Popover::Trigger
+      # DOCS: The trigger for a dropdown. This inherits from the trigger of
+      # a popover as the main functionality comes from there.
     end
   end
 end

data/lib/protos/dropdown.rb

@@ -2,6 +2,14 @@
 
 module Protos
   class Dropdown < Popover
+    # DOCS: A dropdown component is basically a popover with a specific list of
+    # items in a menu. It should be preferred to a popover when the content is
+    # a list of actions rather than some content in its own right.
+    #
+    # Dropdowns, and popovers in general, use tippy.js to position content
+    # rather than pure CSS for accessibility. The layout of pure CSS was too
+    # tricky to get right and we felt the dependency tradeoff was worthwhile.
+
     option :position,
            type: PositionTypes,
            default: -> { :bottom },

data/lib/protos/engine.rb

@@ -2,6 +2,9 @@
 
 module Protos
   class Engine < ::Rails::Engine
+    # DOCS: This is the engine for the Protos gem. It allows autoloading the lib
+    # when used inside a Rails app.
+
     config.autoload_paths += Dir["#{config.root}/lib/"]
   end
 end

data/lib/protos/hero/content.rb

@@ -3,6 +3,9 @@
 module Protos
   class Hero
     class Content < Component
+      # DOCS: The content of a hero. This would be centered within the main
+      # component container.
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/hero/overlay.rb

@@ -3,6 +3,10 @@
 module Protos
   class Hero
     class Overlay < Component
+      # DOCS: The overlay of a hero. This would be used with images to reduce
+      # their opacity through the opacity of the overlay. This can be useful to
+      # make text readable on noisy images.
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/hero.rb

@@ -2,6 +2,10 @@
 
 module Protos
   class Hero < Component
+    # DOCS: A hero component for a page. It will center the content an
+    # optionally layout an image for a responsive layout.
+    # https://daisyui.com/components/hero/
+
     def template(&block)
       div(**attrs, &block)
     end

data/lib/protos/list/item.rb

@@ -3,6 +3,10 @@
 module Protos
   class List
     class Item < Component
+      # DOCS: A single item within a list. Items are joined so that borders will
+      # work for list items, including border radius. E.g. only the first and
+      # last items will have border radius on the top and bottom.
+
       def template(&block)
         li(**attrs, &block)
       end

data/lib/protos/list.rb

@@ -2,6 +2,9 @@
 
 module Protos
   class List < Component
+    # DOCS: A list of items that are joined together for easier styling with
+    # borders, border radius, etc.
+
     option :ordered, Types::Bool, default: -> { false }, reader: false
 
     def template(&block)

data/lib/protos/modal/close_button.rb

@@ -3,6 +3,8 @@
 module Protos
   class Modal
     class CloseButton < Component
+      # DOCS: A close button for a modal
+
       def template(&block)
         form(method: :dialog, class: css[:form]) do
           button(

data/lib/protos/modal/dialog.rb

@@ -3,6 +3,9 @@
 module Protos
   class Modal
     class Dialog < Component
+      # DOCS: A modal dialog. This is the place for the main content of the
+      # modal that will be displayed when the trigger is clicked.
+
       def template(&block)
         dialog(**attrs) do
           div(class: css[:modal], &block)
@@ -13,7 +16,12 @@ module Protos
 
       def theme
         {
-          container: tokens("modal", "modal-bottom", "sm:modal-middle"),
+          container: tokens(
+            "modal",
+            "modal-bottom",
+            "backdrop-blur-sm",
+            "sm:modal-middle"
+          ),
           modal: tokens("modal-box", "flex", "flex-col", "gap-xs")
         }
       end

data/lib/protos/modal/trigger.rb

@@ -3,6 +3,8 @@
 module Protos
   class Modal
     class Trigger < Component
+      # DOCS: A trigger is a button that opens a modal
+
       def template(&block)
         button(**attrs, &block)
       end

data/lib/protos/modal.rb

@@ -2,6 +2,9 @@
 
 module Protos
   class Modal < Protos::Component
+    # DOCS: A modal component that can be triggered by a button or a link and
+    # will open a fullscreen modal, usually with a close button.
+
     def template(&block)
       div(**attrs, class: css[:container], &block)
     end

data/lib/protos/popover/content.rb

@@ -3,6 +3,11 @@
 module Protos
   class Popover
     class Content < Component
+      # DOCS: The content of a popover. We use a <template> element that is
+      # added to the DOM by tippy.js to handle the position of the content.
+      # This means content in here will not be available in system tests that
+      # use rack_test.
+
       def template(&block)
         template_tag(**template_attrs) do
           div(**attrs, &block)

data/lib/protos/popover/trigger.rb

@@ -3,6 +3,9 @@
 module Protos
   class Popover
     class Trigger < Component
+      # DOCS: The trigger of a popover. This is the element that you would hover
+      # or click on to show the popover.
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/popover.rb

@@ -3,7 +3,14 @@
 module Protos
   class Popover < Component
     # DOCS: Like a dropdown, but instead of a list of menu items, its just
-    # a rendered block
+    # a rendered block. The popover is triggered by a button or link.
+    #
+    # Dropdowns, and popovers in general, use tippy.js to position content
+    # rather than pure CSS for accessibility. The layout of pure CSS was too
+    # tricky to get right and we felt the dependency tradeoff was worthwhile.
+    #
+    # Tippy.js options can be passed in via the `options` attribute or, more
+    # conveniently by the typed options listed below.
 
     PositionTypes = Types::Coercible::Symbol.enum(
       :top,

data/lib/protos/stats/actions.rb

@@ -3,6 +3,8 @@
 module Protos
   class Stats
     class Actions < Component
+      # DOCS: A container for the actions (e.g. buttons) for a group of stats
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/stats/description.rb

@@ -3,6 +3,8 @@
 module Protos
   class Stats
     class Description < Component
+      # DOCS: A description for a group of stats
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/stats/figure.rb

@@ -3,6 +3,8 @@
 module Protos
   class Stats
     class Figure < Component
+      # DOCS: A figure for a single stat
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/stats/stat.rb

@@ -3,6 +3,8 @@
 module Protos
   class Stats
     class Stat < Component
+      # DOCS: A single stat container
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/stats/title.rb

@@ -3,6 +3,8 @@
 module Protos
   class Stats
     class Title < Component
+      # DOCS: A title for a group of stats
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/stats/value.rb

@@ -3,6 +3,8 @@
 module Protos
   class Stats
     class Value < Component
+      # DOCS: A value for a single stat
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/stats.rb

@@ -2,6 +2,9 @@
 
 module Protos
   class Stats < Component
+    # DOCS: Stats component that contains a collection of stats
+    # https://daisyui.com/components/stat/
+
     def template(&block)
       div(**attrs, &block)
     end

data/lib/protos/swap/off.rb

@@ -3,6 +3,8 @@
 module Protos
   class Swap
     class Off < Component
+      # DOCS: The off state for a swap component. This is the default state.
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/swap/on.rb

@@ -3,6 +3,8 @@
 module Protos
   class Swap
     class On < Component
+      # DOCS: The on state for a swap component. This is the active state.
+
       def template(&block)
         div(**attrs, &block)
       end

data/lib/protos/swap.rb

@@ -2,6 +2,10 @@
 
 module Protos
   class Swap < Component
+    # DOCS: The swap component is a checkbox that can be toggled on and off to
+    # display different content.
+    # https://daisyui.com/components/swap/
+
     def template
       label(**attrs) do
         input(type: :checkbox, class: css[:input])

data/lib/protos/table/body.rb

@@ -3,6 +3,8 @@
 module Protos
   class Table
     class Body < Component
+      # DOCS: The body of a table
+
       def template(&block)
         tbody(**attrs, &block)
       end

data/lib/protos/table/caption.rb

@@ -3,6 +3,8 @@
 module Protos
   class Table
     class Caption < Component
+      # DOCS: The caption of a table
+
       def template(&block)
         caption(**attrs, &block)
       end