[Improvement] Add docs generator and button documentation (#335)

* Add docs generator and button documentation

Introduce a new generator (`ruby_ui:install:docs`) that copies component
documentation files from the gem to Rails applications. Documentation
files follow the naming convention `{component}_docs.rb` and are copied
to `app/views/docs/` with the `_docs` suffix removed.

Usage:
  bin/rails g ruby_ui:install:docs
  bin/rails g ruby_ui:install:docs --force

Include stub classes for docs dependencies (Views::Base, Docs::Header,
Docs::VisualCodeExample, etc.) so docs files can be loaded without errors.
Rails apps can override these with full implementations.

Includes button component documentation as the first example.

* Add documentation for batch 1 components (#336)

Add docs files for:
- accordion
- alert
- alert_dialog
- aspect_ratio
- avatar
- badge
- breadcrumb
- calendar
- card

Author: djalmaaraujo

CONTRIBUTING.md

@@ -41,4 +41,22 @@ While we don't have specific test coverage requirements, all contributions shoul
 
 If your changes include new components, modify how components should be used, or add new behaviors, it is highly recommended to also open a PR on the [ruby-ui/web](https://github.com/ruby-ui/web) repository. This ensures the documentation website stays up-to-date with the latest component changes.
 
+### Installing Documentation Files
+
+RubyUI includes documentation files for each component that can be installed into your Rails application. These files are located at `lib/ruby_ui/{component}/{component}_docs.rb` and provide usage examples for each component.
+
+To install the documentation files:
+
+```bash
+bin/rails g ruby_ui:install:docs
+```
+
+To overwrite existing documentation files:
+
+```bash
+bin/rails g ruby_ui:install:docs --force
+```
+
+This will copy the documentation files to `app/views/docs/` in your Rails application.
+
 Thank you for contributing to make RubyUI better! 

lib/generators/ruby_ui/install/docs_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RubyUI
+  module Generators
+    module Install
+      class DocsGenerator < Rails::Generators::Base
+        namespace "ruby_ui:install:docs"
+        source_root File.expand_path("../../../ruby_ui", __dir__)
+        class_option :force, type: :boolean, default: false
+
+        def copy_docs_files
+          say "Installing RubyUI documentation files..."
+
+          docs_file_paths.each do |source_path|
+            dest_filename = File.basename(source_path).sub("_docs", "")
+            copy_file source_path, Rails.root.join("app/views/docs", dest_filename), force: options["force"]
+          end
+
+          say ""
+          say "Documentation installed to app/views/docs/", :green
+        end
+
+        private
+
+        def docs_file_paths
+          Dir.glob(File.join(self.class.source_root, "*", "*_docs.rb"))
+        end
+      end
+    end
+  end
+end

lib/ruby_ui/accordion/accordion_docs.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class Views::Docs::Accordion < Views::Base
+  def view_template
+    div(class: "max-w-2xl mx-auto w-full py-10 space-y-10") do
+      component = "Accordion"
+      render Docs::Header.new(title: component,
+        description: "A vertically stacked set of interactive headings that each reveal a section of content.")
+
+      Heading(level: 2) { "Usage" }
+
+      render Docs::VisualCodeExample.new(title: "Example", context: self) do
+        @@code = <<~RUBY
+          div(class: "w-full") do
+            Accordion do
+              AccordionItem do
+                AccordionTrigger do
+                  p(class: "font-medium") { "What is PhlexUI?" }
+                  AccordionIcon()
+                end
+
+                AccordionContent do
+                  p(class: "text-sm pb-4") do
+                    "PhlexUI is a UI component library for Ruby devs who want to build better, faster."
+                  end
+                end
+              end
+            end
+
+            Accordion do
+              AccordionItem do
+                AccordionTrigger do
+                  p(class: "font-medium") { "Can I use it with Rails?" }
+                  AccordionIcon()
+                end
+
+                AccordionContent do
+                  p(class: "text-sm pb-4") do
+                    "Yes, PhlexUI is pure Ruby and works great with Rails. It's a Ruby gem that you can install into your Rails app."
+                  end
+                end
+              end
+            end
+          end
+        RUBY
+      end
+
+      render Components::ComponentSetup::Tabs.new(component_name: component)
+
+      render Docs::ComponentsTable.new(component_files(component))
+    end
+  end
+end

lib/ruby_ui/alert/alert_docs.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+class Views::Docs::Alert < Views::Base
+  def view_template
+    component = "Alert"
+    div(class: "max-w-2xl mx-auto w-full py-10 space-y-10") do
+      render Docs::Header.new(title: "Alert", description: "Displays a callout for user attention.")
+
+      Heading(level: 2) { "Usage" }
+
+      render Docs::VisualCodeExample.new(title: "Example", context: self) do
+        <<~RUBY
+          Alert do
+            rocket_icon
+            AlertTitle { "Pro tip" }
+            AlertDescription { "With RubyUI you'll ship faster." }
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Without Icon", context: self) do
+        <<~RUBY
+          Alert do
+            AlertTitle { "Pro tip" }
+            AlertDescription { "Simply, don't include an icon and your alert will look like this." }
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Warning", context: self) do
+        <<~RUBY
+          Alert(variant: :warning) do
+            info_icon
+            AlertTitle { "Ship often" }
+            AlertDescription { "Shipping is good, your users will thank you for it." }
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Destructive", context: self) do
+        <<~RUBY
+          Alert(variant: :destructive) do
+            alert_icon
+            AlertTitle { "Oopsie daisy!" }
+            AlertDescription { "Your design system is non-existent." }
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "Success", context: self) do
+        <<~RUBY
+          Alert(variant: :success) do
+            check_icon
+            AlertTitle { "Installation successful" }
+            AlertDescription { "You're all set to start using RubyUI in your application." }
+          end
+        RUBY
+      end
+
+      render Components::ComponentSetup::Tabs.new(component_name: component)
+
+      render Docs::ComponentsTable.new(component_files(component))
+    end
+  end
+
+  private
+
+  def rocket_icon
+    svg(
+      xmlns: "http://www.w3.org/2000/svg",
+      viewbox: "0 0 24 24",
+      fill: "currentColor",
+      class: "w-5 h-5"
+    ) do |s|
+      s.path(
+        fill_rule: "evenodd",
+        d:
+          "M9.315 7.584C12.195 3.883 16.695 1.5 21.75 1.5a.75.75 0 01.75.75c0 5.056-2.383 9.555-6.084 12.436A6.75 6.75 0 019.75 22.5a.75.75 0 01-.75-.75v-4.131A15.838 15.838 0 016.382 15H2.25a.75.75 0 01-.75-.75 6.75 6.75 0 017.815-6.666zM15 6.75a2.25 2.25 0 100 4.5 2.25 2.25 0 000-4.5z",
+        clip_rule: "evenodd"
+      )
+      s.path(
+        d:
+          "M5.26 17.242a.75.75 0 10-.897-1.203 5.243 5.243 0 00-2.05 5.022.75.75 0 00.625.627 5.243 5.243 0 005.022-2.051.75.75 0 10-1.202-.897 3.744 3.744 0 01-3.008 1.51c0-1.23.592-2.323 1.51-3.008z"
+      )
+    end
+  end
+
+  def alert_icon
+    svg(
+      xmlns: "http://www.w3.org/2000/svg",
+      viewbox: "0 0 24 24",
+      fill: "currentColor",
+      class: "w-5 h-5"
+    ) do |s|
+      s.path(
+        fill_rule: "evenodd",
+        d:
+          "M9.401 3.003c1.155-2 4.043-2 5.197 0l7.355 12.748c1.154 2-.29 4.5-2.599 4.5H4.645c-2.309 0-3.752-2.5-2.598-4.5L9.4 3.003zM12 8.25a.75.75 0 01.75.75v3.75a.75.75 0 01-1.5 0V9a.75.75 0 01.75-.75zm0 8.25a.75.75 0 100-1.5.75.75 0 000 1.5z",
+        clip_rule: "evenodd"
+      )
+    end
+  end
+
+  def info_icon
+    svg(
+      xmlns: "http://www.w3.org/2000/svg",
+      viewbox: "0 0 24 24",
+      fill: "currentColor",
+      class: "w-5 h-5"
+    ) do |s|
+      s.path(
+        fill_rule: "evenodd",
+        d:
+          "M2.25 12c0-5.385 4.365-9.75 9.75-9.75s9.75 4.365 9.75 9.75-4.365 9.75-9.75 9.75S2.25 17.385 2.25 12zm8.706-1.442c1.146-.573 2.437.463 2.126 1.706l-.709 2.836.042-.02a.75.75 0 01.67 1.34l-.04.022c-1.147.573-2.438-.463-2.127-1.706l.71-2.836-.042.02a.75.75 0 11-.671-1.34l.041-.022zM12 9a.75.75 0 100-1.5.75.75 0 000 1.5z",
+        clip_rule: "evenodd"
+      )
+    end
+  end
+
+  def check_icon
+    svg(
+      xmlns: "http://www.w3.org/2000/svg",
+      viewbox: "0 0 24 24",
+      fill: "currentColor",
+      class: "w-5 h-5"
+    ) do |s|
+      s.path(
+        fill_rule: "evenodd",
+        d:
+          "M2.25 12c0-5.385 4.365-9.75 9.75-9.75s9.75 4.365 9.75 9.75-4.365 9.75-9.75 9.75S2.25 17.385 2.25 12zm13.36-1.814a.75.75 0 10-1.22-.872l-3.236 4.53L9.53 12.22a.75.75 0 00-1.06 1.06l2.25 2.25a.75.75 0 001.14-.094l3.75-5.25z",
+        clip_rule: "evenodd"
+      )
+    end
+  end
+end

lib/ruby_ui/alert_dialog/alert_dialog_docs.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class Views::Docs::AlertDialog < Views::Base
+  def view_template
+    component = "AlertDialog"
+    div(class: "max-w-2xl mx-auto w-full py-10 space-y-10") do
+      render Docs::Header.new(title: "Alert Dialog", description: "A modal dialog that interrupts the user with important content and expects a response.")
+
+      Heading(level: 2) { "Usage" }
+      render Docs::VisualCodeExample.new(title: "Example", context: self) do
+        <<~RUBY
+          AlertDialog do
+            AlertDialogTrigger do
+              Button { "Show dialog" }
+            end
+            AlertDialogContent do
+              AlertDialogHeader do
+                AlertDialogTitle { "Are you absolutely sure?" }
+                AlertDialogDescription { "This action cannot be undone. This will permanently delete your account and remove your data from our servers." }
+              end
+              AlertDialogFooter do
+                AlertDialogCancel { "Cancel" }
+                AlertDialogAction { "Continue" } # Will probably be a link to a controller action (e.g. delete account)
+              end
+            end
+          end
+        RUBY
+      end
+
+      render Components::ComponentSetup::Tabs.new(component_name: component)
+
+      render Docs::ComponentsTable.new(component_files(component))
+    end
+  end
+end

lib/ruby_ui/aspect_ratio/aspect_ratio_docs.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class Views::Docs::AspectRatio < Views::Base
+  def view_template
+    component = "AspectRatio"
+    div(class: "max-w-2xl mx-auto w-full py-10 space-y-10") do
+      render Docs::Header.new(title: "Aspect Ratio", description: "Displays content within a desired ratio.")
+
+      Heading(level: 2) { "Usage" }
+
+      render Docs::VisualCodeExample.new(title: "16/9", context: self) do
+        <<~RUBY
+          AspectRatio(aspect_ratio: "16/9", class: "rounded-md overflow-hidden border shadow-sm") do
+            img(
+              alt: "Placeholder",
+              loading: "lazy",
+              src: image_path('pattern.jpg')
+            )
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "4/3", context: self) do
+        <<~RUBY
+          AspectRatio(aspect_ratio: "4/3", class: "rounded-md overflow-hidden border shadow-sm") do
+            img(
+              alt: "Placeholder",
+              loading: "lazy",
+              src: image_path('pattern.jpg')
+            )
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "1/1", context: self) do
+        <<~RUBY
+          AspectRatio(aspect_ratio: "1/1", class: "rounded-md overflow-hidden border shadow-sm") do
+            img(
+              alt: "Placeholder",
+              loading: "lazy",
+              src: image_path('pattern.jpg')
+            )
+          end
+        RUBY
+      end
+
+      render Docs::VisualCodeExample.new(title: "21/9", context: self) do
+        <<~RUBY
+          AspectRatio(aspect_ratio: "21/9", class: "rounded-md overflow-hidden border shadow-sm") do
+            img(
+              alt: "Placeholder",
+              loading: "lazy",
+              src: image_path('pattern.jpg')
+            )
+          end
+        RUBY
+      end
+
+      render Components::ComponentSetup::Tabs.new(component_name: component)
+
+      render Docs::ComponentsTable.new(component_files(component))
+    end
+  end
+end