flowbite-components 0.1.4 → 0.3.0

data/app/components/flowbite/input_field.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Flowbite
-  # A form element for a single field, containing label, input field, error
-  # messages, helper text and whatever else is needed for a user friendly input
-  # experience.
+  # A fully fledged form element for an attribute containing label, input field,
+  # error messages, helper text and whatever else is needed for a user-friendly
+  # input experience.
   #
   # @see https://flowbite.com/docs/forms/input-field/
   #
@@ -13,54 +13,55 @@ module Flowbite
   # more.
   #
   # Usually you'd use one of the subclasses of this class which implement the
-  # different input types, like `Flowbite::InputField::Text`,
-  # `Flowbite::InputField::Email`, etc.
+  # different input types, like {Flowbite::InputField::Text},
+  # {Flowbite::InputField::Email}, etc.
   #
-  # Expects 2 arguments:
+  # To render an input without labels or error messages etc, see
+  # {Flowbite::Input} instead and one of its subclasses.
   #
-  # @param attribute [Symbol] The name of the attribute to render in this input
-  # field.
+  # @example Basic usage
+  #   <% form_for @person do |form| %>
+  #     <%= render(
+  #       Flowbite::InputField::Number.new(
+  #         attribute: :name,
+  #         form: form
+  #       )
+  #     ) %>
+  #   <% end %>
   #
-  # @param form [ActionView::Helpers::FormBuilder] The form builder object that
-  # will be used to generate the input field.
+  # @example Kitchen sink
+  #   <% form_for @person do |form| %>
+  #     <%= render(
+  #       Flowbite::InputField::Number.new(
+  #         attribute: :name,
+  #         class: ["mb-4", "w-full"],
+  #         disabled: true,
+  #         form: form,
+  #         hint: {
+  #           content: "Please enter your full name.",
+  #           options: {id: "name-helper-text"}
+  #         },
+  #         input: {
+  #           options: {placeholder: "All of your names here"}
+  #         },
+  #         label: {
+  #           content: "Full name",
+  #           options: {class: ["mb-2", "font-medium"]}
+  #         },
+  #         options: {data: {controller: "form-field"}},
+  #         size: :lg
+  #       )
+  #     ) %>
+  #   <% end %>
   #
-  # Supports additional arguments:
+  # @viewcomponent_slot [Flowbite::Input::Hint] hint Helper text displayed
+  #   below the input field to provide additional context or instructions.
+  # @viewcomponent_slot [Flowbite::Input] input The input element itself.
+  #   Usually auto-generated based on the input type subclass.
+  # @viewcomponent_slot [Flowbite::Input::Label] label The label for the input
+  #   field, rendered above the input element.
   #
-  # @param hint [String] A hint to display below the input field, providing
-  # additional context or instructions for the user. This is optional. See
-  # https://flowbite.com/docs/forms/input-field/#helper-text
-  #
-  # @param label [Hash] A hash with options for the label. These are passed to
-  # Flowbite::Input::Label, see that for details. Can contain:
-  # - `content`: The content of the label. If not provided, the label will
-  #   default to the attribute name.
-  # - `options`: A hash of additional options to pass to the label component.
-  #   This can be used to set the class, for example.
-  #
-  # @param disabled [Boolean] Whether the input field should be disabled.
-  # Defaults to `false`.
-  #
-  # @param input [Hash] A hash with options for the default input component.
-  # These are passed to the input components constructor, so see whatever
-  # component is being used for details. Can contain:
-  # - `options`: Additional HTML attributes to pass to the input element.
-  #
-  # @param size [Symbol] The size of the input field. Can be one of `:sm`,
-  # `:md`, or `:lg`. Defaults to `:md`.
-  #
-  # Sample usage
-  #
-  #     <% form_for @person do |form| %>
-  #       <%= render(
-  #         Flowbite::InputField::Number.new(
-  #           :attribute => :name,
-  #           :form => form
-  #         )
-  #       ) %>
-  #     <% end %>
-  #
-  # To render an input without labels or error messages etc, use
-  # `Flowbite::Input::Field` instead.
+  # @lookbook_embed InputFieldPreview
   class InputField < ViewComponent::Base
     renders_one :hint
     renders_one :input
@@ -75,6 +76,45 @@ module Flowbite
       @object.errors[@attribute] || []
     end
 
+    # @param attribute [Symbol] The name of the attribute to render in this
+    #   input field.
+    #
+    # @param form [ActionView::Helpers::FormBuilder] The form builder object that
+    #   will be used to generate the input field.
+    #
+    # @param class [String, Array<String>] Additional CSS classes to apply to
+    #   the input field container, i.e. the outermost element. To add classes to
+    #   individual components of the InputField, use the +input+, +label+ and
+    #   +hint+ arguments.
+    #
+    # @param disabled [Boolean] Whether the input field should be disabled.
+    #
+    # @param hint [Hash] A hint to display below the input field, providing
+    #   additional context or instructions for the user. If provided, this Hash
+    #   is passed to the {Flowbite::Input::Hint} constructor.
+    # @option hint [String] content The content of the hint element.
+    # @option hint [Hash] options Additional options to pass to the hint
+    #   component. This can be used to set the class, for example.
+    #
+    # @param input [Hash] A hash with options for the input component.
+    #   These are passed to the input component's constructor, see the
+    #   documentation for whatever input component is being used.
+    #   See {Flowbite::Input}.
+    # @option input [Hash] options Additional HTML attributes to pass to
+    #   the input element.
+    #
+    # @param label [Hash] A hash with options for the label element. If
+    #   provided, this Hash is passed to the {Flowbite::Input::Label}
+    #   constructor.
+    # @option label [String] content The content of the label element.
+    # @option label [Hash] options Additional options to pass to the label
+    #   component. This can be used to set the class, for example.
+    #
+    # @param options [Hash] Additional HTML attributes to pass to the input
+    #   field container element.
+    #
+    # @param size [Symbol] The size of the input field. Can be one of +:sm+,
+    #   +:default+, or +:lg+.
     def initialize(attribute:, form:, class: nil, disabled: false, hint: nil, input: {}, label: {}, options: {}, size: :default)
       @attribute = attribute
       @class = Array.wrap(binding.local_variable_get(:class))
@@ -89,7 +129,7 @@ module Flowbite
     end
 
     def input_component
-      ::Flowbite::Input::Field
+      ::Flowbite::Input
     end
 
     protected
@@ -102,6 +142,10 @@ module Flowbite
       end
     end
 
+    def container_options
+      @options.merge({class: classes.join(" ")})
+    end
+
     def default_container_classes
       []
     end
@@ -111,11 +155,19 @@ module Flowbite
       return unless hint?
 
       component = Flowbite::Input::Hint.new(
+        **default_hint_arguments
+      ).with_content(default_hint_content)
+      render(component)
+    end
+
+    # @return [Hash] The keyword arguments for the hint component.
+    def default_hint_arguments
+      {
         attribute: @attribute,
+        class: @hint[:class],
         form: @form,
         options: default_hint_options
-      ).with_content(default_hint_content)
-      render(component)
+      }
     end
 
     def default_hint_content
@@ -136,23 +188,37 @@ module Flowbite
       }.merge(@hint[:options] || {})
     end
 
+    # Returns the HTML to use for the default input element.
+    def default_input
+      render(input_component.new(**default_input_arguments))
+    end
+
+    # @return [Hash] The keyword arguments for the default input component.
+    def default_input_arguments
+      {
+        attribute: @attribute,
+        class: @input[:class],
+        disabled: @disabled,
+        form: @form,
+        options: default_input_options,
+        size: @size
+      }
+    end
+
     # Returns a Hash with the default attributes to apply to the input element.
     #
     # The default attributes can be overriden by passing the `input[options]`
     # argument to the constructor.
     def default_input_options
-      if hint?
+      options = if hint?
         {
           "aria-describedby": id_for_hint_element
         }
       else
         {}
       end
-    end
 
-    # Returns the HTML to use for the default input element.
-    def default_input
-      render(input_component.new(**input_arguments))
+      options.merge(@input[:options] || {})
     end
 
     def default_label
@@ -197,20 +263,5 @@ module Flowbite
         .compact_blank
         .join("_")
     end
-
-    # @return [Hash] The keyword arguments for the input component.
-    def input_arguments
-      {
-        attribute: @attribute,
-        disabled: @disabled,
-        form: @form,
-        options: input_options,
-        size: @size
-      }
-    end
-
-    def input_options
-      default_input_options.merge(@input[:options] || {})
-    end
   end
 end

data/app/components/flowbite/link.rb

@@ -5,6 +5,8 @@ module Flowbite
   # to an external website when clicking on an inline text item, button, or card
   #
   # Use this component to add default styles to an inline link element.
+  #
+  # @lookbook_embed LinkPreview
   class Link < ViewComponent::Base
     attr_reader :href, :options
 

data/app/components/flowbite/sidebar/item.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Flowbite
+  class Sidebar
+    # Renders a sidebar navigation item.
+    #
+    # Each item renders as a list item containing a link. Optionally, an icon
+    # can be provided using the +icon+ slot, which will be displayed before the
+    # label text.
+    #
+    # @example Basic item
+    #   <%= render Flowbite::Sidebar::Item.new(href: "/dashboard") { "Dashboard" } %>
+    #
+    # @example Item with icon
+    #   <%= render(Flowbite::Sidebar::Item.new(href: "/dashboard")) do |item| %>
+    #     <% item.with_icon do %>
+    #       <svg class="w-5 h-5" ...>...</svg>
+    #     <% end %>
+    #     Dashboard
+    #   <% end %>
+    #
+    # @viewcomponent_slot icon An optional icon displayed before the label text.
+    class Item < ViewComponent::Base
+      renders_one :icon
+
+      attr_reader :href, :options
+
+      class << self
+        def classes
+          [
+            "flex", "items-center", "px-2", "py-1.5", "text-body",
+            "rounded-base", "hover:bg-neutral-tertiary", "hover:text-fg-brand", "group"
+          ]
+        end
+      end
+
+      # @param class [Array<String>] Additional CSS classes for the link element.
+      # @param href [String] The URL for the navigation link.
+      # @param options [Hash] Additional HTML attributes for the link element.
+      def initialize(href:, class: nil, **options)
+        super()
+        @class = Array.wrap(binding.local_variable_get(:class))
+        @href = href
+        @options = options
+      end
+
+      def call
+        content_tag(:li) do
+          link_options = {class: link_classes}.merge(options)
+          content_tag(:a, href: href, **link_options) do
+            concat(icon) if icon?
+            concat(content_tag(:span, content, class: label_classes))
+          end
+        end
+      end
+
+      private
+
+      def label_classes
+        "ms-3" if icon?
+      end
+
+      def link_classes
+        self.class.classes + @class
+      end
+    end
+  end
+end

data/app/components/flowbite/sidebar/navigation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Flowbite
+  class Sidebar
+    # Renders the navigation list for a sidebar.
+    #
+    # This component renders a +<ul>+ with navigation items. It can be used
+    # inside a {Flowbite::Sidebar} for a fixed-position sidebar, or standalone
+    # in any layout that needs sidebar-style navigation.
+    #
+    # @example Inside a Sidebar
+    #   <%= render(Flowbite::Sidebar.new) do %>
+    #     <%= render(Flowbite::Sidebar::Navigation.new) do |nav| %>
+    #       <% nav.with_item do %>
+    #         <%= render(Flowbite::Sidebar::Item.new(href: "/")) { "Home" } %>
+    #       <% end %>
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example Standalone
+    #   <%= render(Flowbite::Sidebar::Navigation.new) do |nav| %>
+    #     <% nav.with_item do %>
+    #       <%= render(Flowbite::Sidebar::Item.new(href: "/")) { "Home" } %>
+    #     <% end %>
+    #   <% end %>
+    class Navigation < ViewComponent::Base
+      renders_many :items
+
+      class << self
+        def classes
+          ["space-y-2", "font-medium"]
+        end
+      end
+
+      # @param class [Array<String>] Additional CSS classes for the list element.
+      # @param options [Hash] Additional HTML options for the list element.
+      def initialize(class: nil, **options)
+        super()
+        @class = Array.wrap(binding.local_variable_get(:class))
+        @options = options
+      end
+
+      def call
+        content_tag(:ul, list_options) do
+          items.each do |item|
+            concat(item)
+          end
+        end
+      end
+
+      private
+
+      def list_classes
+        self.class.classes + @class
+      end
+
+      def list_options
+        {class: list_classes}.merge(@options)
+      end
+    end
+  end
+end

data/app/components/flowbite/sidebar.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Flowbite
+  # Renders a fixed-position sidebar container.
+  #
+  # Use {Flowbite::Sidebar} as the outer shell and
+  # {Flowbite::Sidebar::Navigation} inside it to render the list of
+  # {Flowbite::Sidebar::Item}s.
+  #
+  # @example Usage
+  #   <%= render(Flowbite::Sidebar.new) do %>
+  #     <%= render(Flowbite::Sidebar::Navigation.new) do |nav| %>
+  #       <% nav.with_item do %>
+  #         <%= render(Flowbite::Sidebar::Item.new(href: "/dashboard")) { "Dashboard" } %>
+  #       <% end %>
+  #     <% end %>
+  #   <% end %>
+  #
+  # @see https://flowbite.com/docs/components/sidebar/
+  # @lookbook_embed SidebarPreview
+  class Sidebar < ViewComponent::Base
+    class << self
+      def classes
+        [
+          "fixed", "top-0", "left-0", "z-40", "w-64", "h-screen",
+          "transition-transform", "-translate-x-full", "sm:translate-x-0"
+        ]
+      end
+    end
+
+    # @param class [Array<String>] Additional CSS classes for the sidebar
+    #   container.
+    # @param options [Hash] Additional HTML options for the sidebar container.
+    def initialize(class: nil, **options)
+      super()
+      @class = Array.wrap(binding.local_variable_get(:class))
+      @options = options
+    end
+
+    def call
+      content_tag(:aside, aside_options) do
+        content_tag(:div, class: wrapper_classes) do
+          content
+        end
+      end
+    end
+
+    private
+
+    def aside_classes
+      self.class.classes + @class
+    end
+
+    def aside_options
+      {class: aside_classes, "aria-label": "Sidebar"}.merge(@options)
+    end
+
+    def wrapper_classes
+      ["h-full", "px-3", "py-4", "overflow-y-auto", "bg-neutral-primary-soft"]
+    end
+  end
+end

data/app/components/flowbite/toast/icon.html.erb

@@ -0,0 +1,5 @@
+<div class="<%= container_classes.join(" ") %>">
+  <svg class="w-4 h-4" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
+    <path d="<%= svg_path %>"/>
+  </svg>
+</div>

data/app/components/flowbite/toast/icon.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Flowbite
+  class Toast
+    # Renders an icon for a toast notification.
+    #
+    # @param style [Symbol] The color style of the icon (:default, :success, :danger, :warning).
+    class Icon < ViewComponent::Base
+      class << self
+        def classes(style: :default)
+          styles.fetch(style).fetch(:classes)
+        end
+
+        def svg_path(style: :default)
+          styles.fetch(style).fetch(:svg_path)
+        end
+
+        # rubocop:disable Layout/LineLength
+        def styles
+          {
+            default: {
+              classes: ["inline-flex", "items-center", "justify-center", "shrink-0", "w-8", "h-8", "text-blue-500", "bg-blue-100", "rounded-lg", "dark:bg-blue-800", "dark:text-blue-200"],
+              svg_path: "M15.147 15.085a7.159 7.159 0 0 1-6.189 3.307A6.713 6.713 0 0 1 3.1 15.444c-2.679-4.513.287-8.737.888-9.548A4.373 4.373 0 0 0 5 1.608c1.287.953 6.445 3.218 5.537 10.5 1.5-1.122 2.706-3.01 2.853-6.14 1.433 1.049 3.993 5.395 1.757 9.117Z"
+            },
+            success: {
+              classes: ["inline-flex", "items-center", "justify-center", "shrink-0", "w-8", "h-8", "text-green-500", "bg-green-100", "rounded-lg", "dark:bg-green-800", "dark:text-green-200"],
+              svg_path: "M10 .5a9.5 9.5 0 1 0 9.5 9.5A9.51 9.51 0 0 0 10 .5Zm3.707 8.207-4 4a1 1 0 0 1-1.414 0l-2-2a1 1 0 0 1 1.414-1.414L9 10.586l3.293-3.293a1 1 0 0 1 1.414 1.414Z"
+            },
+            danger: {
+              classes: ["inline-flex", "items-center", "justify-center", "shrink-0", "w-8", "h-8", "text-red-500", "bg-red-100", "rounded-lg", "dark:bg-red-800", "dark:text-red-200"],
+              svg_path: "M10 .5a9.5 9.5 0 1 0 9.5 9.5A9.51 9.51 0 0 0 10 .5Zm3.707 11.793a1 1 0 1 1-1.414 1.414L10 11.414l-2.293 2.293a1 1 0 0 1-1.414-1.414L8.586 10 6.293 7.707a1 1 0 0 1 1.414-1.414L10 8.586l2.293-2.293a1 1 0 0 1 1.414 1.414L11.414 10l2.293 2.293Z"
+            },
+            warning: {
+              classes: ["inline-flex", "items-center", "justify-center", "shrink-0", "w-8", "h-8", "text-orange-500", "bg-orange-100", "rounded-lg", "dark:bg-orange-700", "dark:text-orange-200"],
+              svg_path: "M10 .5a9.5 9.5 0 1 0 9.5 9.5A9.51 9.51 0 0 0 10 .5ZM10 15a1 1 0 1 1 0-2 1 1 0 0 1 0 2Zm1-4a1 1 0 0 1-2 0V6a1 1 0 0 1 2 0v5Z"
+            }
+          }.freeze
+        end
+        # rubocop:enable Layout/LineLength
+      end
+
+      attr_reader :style
+
+      def initialize(style: :default)
+        @style = style
+      end
+
+      def container_classes
+        self.class.classes(style: style)
+      end
+
+      def svg_path
+        self.class.svg_path(style: style)
+      end
+    end
+  end
+end

data/app/components/flowbite/toast/toast.html.erb

@@ -0,0 +1,40 @@
+<%= tag.div(
+  class: container_classes.join(" "),
+  role: "alert",
+  **options,
+) do %>
+  <%= render Flowbite::Toast::Icon.new(style: style) %>
+
+  <div class="ms-3 text-sm font-normal"><%= message %></div>
+
+  <% if dismissible %>
+    <%# Styles from https://flowbite.com/docs/components/toast/#default-toast %>
+    <button
+      type="button"
+      class="
+        ms-auto flex items-center justify-center text-body
+        hover:text-heading bg-transparent box-border border
+        border-transparent hover:bg-neutral-secondary-medium focus:ring-4
+        focus:ring-neutral-tertiary font-medium leading-5 rounded text-sm
+        h-8 w-8 focus:outline-none
+      "
+      aria-label="Close"
+    >
+      <svg
+        class="w-3 h-3"
+        aria-hidden="true"
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 14 14"
+      >
+        <path
+          stroke="currentColor"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          stroke-width="2"
+          d="m1 1 6 6m0 0 6 6M7 7l6-6M7 7l-6 6"
+        />
+      </svg>
+    </button>
+  <% end %>
+<% end %>

data/app/components/flowbite/toast.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Flowbite
+  # Renders a toast notification element.
+  #
+  # @example Usage
+  #  <%= render(Flowbite::Toast.new(message: "Something has happened!")) %>
+  #
+  # @see https://flowbite.com/docs/components/toast/
+  # @lookbook_embed ToastPreview
+  class Toast < ViewComponent::Base
+    class << self
+      def classes
+        ["flex", "items-center", "w-full", "max-w-xs", "p-4", "text-body", "bg-neutral-primary-soft", "rounded-base", "shadow-xs", "border", "border-default"]
+      end
+    end
+
+    attr_reader :dismissible, :message, :options, :style
+
+    # @param class [Array<String>] Additional CSS classes for the toast container.
+    # @param dismissible [Boolean] Whether the toast can be dismissed (default: true).
+    # @param message [String] The message to display in the toast.
+    # @param options [Hash] Additional HTML options for the toast container.
+    # @param style [Symbol] The color style of the toast (:default, :success, :danger, :warning).
+    def initialize(message:, dismissible: true, style: :default, class: nil, **options)
+      @message = message
+      @style = style
+      @dismissible = dismissible
+      @class = Array.wrap(binding.local_variable_get(:class))
+      @options = options
+    end
+
+    def container_classes
+      self.class.classes + @class
+    end
+  end
+end

data/lib/flowbite/components/version.rb

@@ -2,6 +2,6 @@
 
 module Flowbite
   module Components
-    VERSION = "0.1.4"
+    VERSION = "0.3.0"
   end
 end

data/lib/yard/flowbite_viewcomponent.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# YARD plugin for documenting ViewComponent slots
+#
+# This plugin adds a @viewcomponent_slot tag that can be used to document
+# slots defined with renders_one and renders_many in ViewComponent classes.
+#
+# Usage:
+#   # @viewcomponent_slot [Flowbite::Card::Title] title The title of the card
+#   renders_one :title
+#
+#   # @viewcomponent_slot [Flowbite::Breadcrumb::Item] items The breadcrumb items
+#   renders_many :items
+#
+# The tag accepts:
+#   - Types (optional): The component class(es) that can be rendered in the slot
+#   - Name (required): The slot name (matching the symbol passed to renders_one/renders_many)
+#   - Description (optional): A description of what the slot is for
+
+YARD::Tags::Library.define_tag(
+  "ViewComponent Slot",
+  :viewcomponent_slot,
+  :with_types_and_name
+)