maquina-components 0.1.1 → 0.2.0

data/app/assets/stylesheets/toggle_group.css

@@ -0,0 +1,151 @@
+/* ===== Toggle Group Component Styles ===== */
+/*
+ * A group of two-state buttons that can be toggled on or off.
+ * Uses data attributes for styling to avoid inline utility classes.
+ * Fully compatible with dark mode via CSS variables.
+ *
+ * Structure:
+ * - toggle-group (root container)
+ *   - item (toggle button)
+ */
+
+/* ===== Root Container ===== */
+[data-component="toggle-group"] {
+  display: inline-flex;
+  align-items: center;
+  @apply gap-1 rounded-md;
+}
+
+/* Group disabled state */
+[data-component="toggle-group"][aria-disabled="true"] {
+  @apply opacity-50 pointer-events-none;
+}
+
+/* ===== Toggle Item Base ===== */
+[data-toggle-group-part="item"] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  @apply gap-2 rounded-md text-sm font-medium;
+  @apply transition-colors duration-150;
+  
+  /* Default size */
+  @apply h-9 px-3;
+  
+  /* Remove default button styles */
+  border: none;
+  cursor: pointer;
+  
+  /* Default variant colors */
+  background-color: transparent;
+  color: var(--muted-foreground);
+}
+
+/* ===== Size Variants ===== */
+
+/* Small */
+[data-component="toggle-group"][data-size="sm"] [data-toggle-group-part="item"] {
+  @apply h-8 px-2.5 text-xs;
+}
+
+/* Large */
+[data-component="toggle-group"][data-size="lg"] [data-toggle-group-part="item"] {
+  @apply h-10 px-4;
+}
+
+/* ===== Visual Variants ===== */
+
+/* Default variant */
+[data-component="toggle-group"][data-variant="default"] [data-toggle-group-part="item"] {
+  background-color: transparent;
+}
+
+[data-component="toggle-group"][data-variant="default"] [data-toggle-group-part="item"]:hover:not(:disabled) {
+  background-color: var(--muted);
+  color: var(--muted-foreground);
+}
+
+[data-component="toggle-group"][data-variant="default"] [data-toggle-group-part="item"][data-state="on"] {
+  background-color: var(--accent);
+  color: var(--accent-foreground);
+}
+
+/* Outline variant */
+[data-component="toggle-group"][data-variant="outline"] {
+  background-color: transparent;
+  border: 1px solid var(--border);
+  @apply gap-0;
+}
+
+[data-component="toggle-group"][data-variant="outline"] [data-toggle-group-part="item"] {
+  @apply rounded-none;
+  border-right: 1px solid var(--border);
+}
+
+[data-component="toggle-group"][data-variant="outline"] [data-toggle-group-part="item"]:first-child {
+  @apply rounded-l-md;
+}
+
+[data-component="toggle-group"][data-variant="outline"] [data-toggle-group-part="item"]:last-child {
+  @apply rounded-r-md;
+  border-right: none;
+}
+
+[data-component="toggle-group"][data-variant="outline"] [data-toggle-group-part="item"]:hover:not(:disabled) {
+  background-color: var(--muted);
+  color: var(--muted-foreground);
+}
+
+[data-component="toggle-group"][data-variant="outline"] [data-toggle-group-part="item"][data-state="on"] {
+  background-color: var(--accent);
+  color: var(--accent-foreground);
+}
+
+/* ===== Interactive States ===== */
+
+/* Hover */
+[data-toggle-group-part="item"]:hover:not(:disabled) {
+  background-color: var(--muted);
+  color: var(--muted-foreground);
+}
+
+/* Pressed (on) state */
+[data-toggle-group-part="item"][data-state="on"] {
+  background-color: var(--accent);
+  color: var(--accent-foreground);
+}
+
+/* Focus visible */
+[data-toggle-group-part="item"]:focus-visible {
+  @apply outline-none;
+  box-shadow: 0 0 0 2px var(--background),
+              0 0 0 4px var(--ring);
+  z-index: 1;
+  position: relative;
+}
+
+/* Disabled */
+[data-toggle-group-part="item"]:disabled {
+  @apply opacity-50 cursor-not-allowed pointer-events-none;
+}
+
+/* ===== Icon Support ===== */
+[data-toggle-group-part="item"] svg {
+  @apply size-4 shrink-0 pointer-events-none;
+}
+
+/* Icon-only size adjustments */
+[data-component="toggle-group"][data-size="sm"] [data-toggle-group-part="item"] svg {
+  @apply size-3.5;
+}
+
+[data-component="toggle-group"][data-size="lg"] [data-toggle-group-part="item"] svg {
+  @apply size-5;
+}
+
+/* ===== Dark Mode ===== */
+/*
+ * Dark mode is handled automatically through CSS variables.
+ * The theme variables change based on the .dark class on html/body.
+ * No additional dark mode styles needed here.
+ */

data/app/assets/tailwind/maquina_components_engine/engine.css

@@ -0,0 +1,16 @@
+@source "../../../views/";
+
+@layer components {
+  @import "../../stylesheets/alert.css";
+  @import "../../stylesheets/badge.css";
+  @import "../../stylesheets/breadcrumbs.css";
+  @import "../../stylesheets/card.css";
+  @import "../../stylesheets/dropdown_menu.css";
+  @import "../../stylesheets/empty.css";
+  @import "../../stylesheets/form.css";
+  @import "../../stylesheets/header.css";
+  @import "../../stylesheets/pagination.css";
+  @import "../../stylesheets/sidebar.css";
+  @import "../../stylesheets/table.css";
+  @import "../../stylesheets/toggle_group.css";
+}

data/app/helpers/maquina_components/breadcrumbs_helper.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module MaquinaComponents
+  # Breadcrumbs Helper
+  #
+  # Provides helper methods for rendering breadcrumb navigation.
+  # Supports both simple hash-based API and composable partials.
+  #
+  module BreadcrumbsHelper
+    # Render breadcrumbs from a hash of links
+    #
+    # @param links [Hash] Hash of text => path pairs
+    # @param current_page [String, nil] Text for current page (no link)
+    # @param css_classes [String] Additional CSS classes for nav element
+    # @return [String] HTML string
+    #
+    # @example Basic usage
+    #   breadcrumbs({"Home" => root_path, "Users" => users_path}, "John Doe")
+    #
+    # @example Without current page
+    #   breadcrumbs({"Home" => root_path, "Users" => users_path})
+    #
+    def breadcrumbs(links = {}, current_page = nil, css_classes: "")
+      render "components/breadcrumbs", css_classes: css_classes do
+        render "components/breadcrumbs/list" do
+          build_breadcrumb_items(links, current_page, responsive: false)
+        end
+      end
+    end
+
+    # Render responsive breadcrumbs that auto-collapse on overflow
+    #
+    # Uses Stimulus controller to hide middle items when space is limited,
+    # showing an ellipsis element instead.
+    #
+    # @param links [Hash] Hash of text => path pairs
+    # @param current_page [String, nil] Text for current page (no link)
+    # @param css_classes [String] Additional CSS classes for nav element
+    # @return [String] HTML string
+    #
+    # @example
+    #   responsive_breadcrumbs(
+    #     {"Home" => root_path, "Docs" => docs_path, "Components" => components_path},
+    #     "Button"
+    #   )
+    #
+    def responsive_breadcrumbs(links = {}, current_page = nil, css_classes: "")
+      render "components/breadcrumbs", css_classes: css_classes, responsive: true do
+        render "components/breadcrumbs/list" do
+          build_breadcrumb_items(links, current_page, responsive: true)
+        end
+      end
+    end
+
+    private
+
+    # Build breadcrumb items from links hash
+    #
+    # @param links [Hash] Hash of text => path pairs
+    # @param current_page [String, nil] Text for current page
+    # @param responsive [Boolean] Whether to include Stimulus targets
+    # @return [String] Safe-joined HTML string
+    #
+    def build_breadcrumb_items(links, current_page, responsive: false)
+      items = []
+      link_array = links.to_a
+
+      link_array.each_with_index do |(text, path), index|
+        # Determine if this is a collapsible middle item (not first or last)
+        is_middle = responsive && index > 0 && (index < link_array.size - 1 || current_page.present?)
+        item_data = is_middle ? {breadcrumb_target: "item"} : {}
+
+        items << capture do
+          render "components/breadcrumbs/item", data: item_data do
+            render "components/breadcrumbs/link", href: path do
+              text
+            end
+          end
+        end
+
+        # Add separator after each link
+        items << capture do
+          render "components/breadcrumbs/separator"
+        end
+
+        # Insert ellipsis after first item for responsive mode
+        if responsive && index == 0 && (link_array.size > 2 || (link_array.size > 1 && current_page.present?))
+          items << capture do
+            render "components/breadcrumbs/item", css_classes: "hidden", data: {breadcrumb_target: "ellipsis"} do
+              render "components/breadcrumbs/ellipsis"
+            end
+          end
+
+          items << capture do
+            render "components/breadcrumbs/separator", css_classes: "hidden", data: {breadcrumb_target: "ellipsisSeparator"}
+          end
+        end
+      end
+
+      # Add current page if provided
+      if current_page.present?
+        # Remove last separator since current page follows
+        items << capture do
+          render "components/breadcrumbs/item" do
+            render "components/breadcrumbs/page" do
+              current_page
+            end
+          end
+        end
+      else
+        # Remove trailing separator if no current page
+        items.pop
+      end
+
+      safe_join(items)
+    end
+  end
+end

data/app/helpers/maquina_components/dropdown_menu_helper.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module MaquinaComponents
+  # DropdownMenu Helper
+  #
+  # Provides a builder pattern for creating dropdown menus with a clean API.
+  #
+  # @example Basic usage
+  #   <%= dropdown_menu do |menu| %>
+  #     <% menu.trigger { "Options" } %>
+  #     <% menu.content do %>
+  #       <% menu.item "Profile", href: profile_path %>
+  #       <% menu.item "Settings", href: settings_path %>
+  #     <% end %>
+  #   <% end %>
+  #
+  # @example With icons and shortcuts
+  #   <%= dropdown_menu do |menu| %>
+  #     <% menu.trigger variant: :ghost, size: :icon do %>
+  #       <%= icon_for :more_horizontal %>
+  #     <% end %>
+  #     <% menu.content align: :end, width: :md do %>
+  #       <% menu.label "Actions" %>
+  #       <% menu.item "Edit", href: edit_path, icon: :pencil do |item| %>
+  #         <% item.shortcut "⌘E" %>
+  #       <% end %>
+  #       <% menu.separator %>
+  #       <% menu.item "Delete", href: delete_path, method: :delete, variant: :destructive, icon: :trash %>
+  #     <% end %>
+  #   <% end %>
+  #
+  # @example Simple data-driven menu
+  #   <%= dropdown_menu_simple "Actions", items: [
+  #     { label: "Edit", href: edit_path, icon: :pencil },
+  #     { label: "Delete", href: delete_path, method: :delete, destructive: true }
+  #   ] %>
+  #
+  module DropdownMenuHelper
+    # Renders a dropdown menu using the builder pattern
+    #
+    # @param css_classes [String] Additional CSS classes for the root element
+    # @param html_options [Hash] Additional HTML attributes
+    # @yield [DropdownMenuBuilder] Builder instance for constructing the menu
+    # @return [String] Rendered HTML
+    def dropdown_menu(css_classes: "", **html_options, &block)
+      builder = DropdownMenuBuilder.new(self)
+      capture(builder, &block)
+
+      render "components/dropdown_menu", css_classes: css_classes, **html_options do
+        builder.to_html
+      end
+    end
+
+    # Renders a simple dropdown menu from data
+    #
+    # @param trigger_text [String] Text for the trigger button
+    # @param items [Array<Hash>] Array of item configurations
+    # @param trigger_options [Hash] Options for the trigger button
+    # @param content_options [Hash] Options for the content container
+    # @return [String] Rendered HTML
+    def dropdown_menu_simple(trigger_text, items:, trigger_options: {}, content_options: {})
+      dropdown_menu do |menu|
+        menu.trigger(**trigger_options) { trigger_text }
+
+        menu.content(**content_options) do
+          items.each do |item|
+            if item[:separator]
+              menu.separator
+            elsif item[:label] && item[:href].nil? && item[:action].nil?
+              menu.label item[:label]
+            else
+              variant = item[:destructive] ? :destructive : :default
+              menu.item(
+                item[:label],
+                href: item[:href],
+                method: item[:method],
+                icon: item[:icon],
+                variant: variant,
+                disabled: item[:disabled]
+              )
+            end
+          end
+        end
+      end
+    end
+
+    # Builder class for constructing dropdown menus
+    class DropdownMenuBuilder
+      def initialize(view_context)
+        @view = view_context
+        @trigger_content = nil
+        @content_block = nil
+      end
+
+      # Defines the trigger button
+      #
+      # @param variant [Symbol] Button variant
+      # @param size [Symbol] Button size
+      # @param as_child [Boolean] Whether to use custom trigger markup
+      # @param options [Hash] Additional options
+      # @yield Block for trigger content
+      def trigger(variant: :outline, size: :default, as_child: false, **options, &block)
+        @trigger_options = {variant: variant, size: size, as_child: as_child, **options}
+        @trigger_content = @view.capture(&block)
+      end
+
+      # Defines the menu content
+      #
+      # @param align [Symbol] Horizontal alignment
+      # @param side [Symbol] Which side to open
+      # @param width [Symbol] Width preset
+      # @param options [Hash] Additional options
+      # @yield Block containing menu items
+      def content(align: :start, side: :bottom, width: :default, **options, &block)
+        @content_options = {align: align, side: side, width: width, **options}
+        @content_builder = DropdownMenuContentBuilder.new(@view)
+        @view.capture(@content_builder, &block)
+      end
+
+      # Generates the final HTML
+      def to_html
+        parts = []
+
+        if @trigger_content
+          parts << @view.render(
+            "components/dropdown_menu/trigger",
+            **@trigger_options
+          ) { @trigger_content }
+        end
+
+        if @content_builder
+          parts << @view.render(
+            "components/dropdown_menu/content",
+            **@content_options
+          ) { @content_builder.to_html }
+        end
+
+        @view.safe_join(parts)
+      end
+    end
+
+    # Builder for dropdown menu content
+    class DropdownMenuContentBuilder
+      def initialize(view_context)
+        @view = view_context
+        @parts = []
+      end
+
+      # Adds a menu item
+      #
+      # @param label [String, nil] Item label (alternative to block)
+      # @param href [String, nil] URL for the item
+      # @param method [Symbol, nil] HTTP method
+      # @param icon [Symbol, nil] Icon name
+      # @param variant [Symbol] Visual variant
+      # @param disabled [Boolean] Whether disabled
+      # @param options [Hash] Additional options
+      # @yield Optional block for custom content or item builder
+      def item(label = nil, href: nil, method: nil, icon: nil, variant: :default, disabled: false, **options, &block)
+        item_builder = DropdownMenuItemBuilder.new(@view)
+
+        content = if block
+          @view.capture(item_builder, &block)
+        elsif label
+          build_item_content(label, icon)
+        end
+
+        # Append shortcut if defined via builder
+        content = @view.safe_join([content, item_builder.shortcut_html].compact) if item_builder.shortcut_html
+
+        @parts << @view.render(
+          "components/dropdown_menu/item",
+          href: href,
+          method: method,
+          variant: variant,
+          disabled: disabled,
+          **options
+        ) { content }
+      end
+
+      # Adds a label/heading
+      #
+      # @param text [String, nil] Label text
+      # @param inset [Boolean] Whether to indent
+      # @param options [Hash] Additional options
+      # @yield Optional block for custom content
+      def label(text = nil, inset: false, **options, &block)
+        @parts << @view.render(
+          "components/dropdown_menu/label",
+          text: text,
+          inset: inset,
+          **options,
+          &block
+        )
+      end
+
+      # Adds a separator
+      #
+      # @param options [Hash] Additional options
+      def separator(**options)
+        @parts << @view.render("components/dropdown_menu/separator", **options)
+      end
+
+      # Adds a group
+      #
+      # @param options [Hash] Additional options
+      # @yield Block containing group items
+      def group(**options, &block)
+        group_builder = DropdownMenuContentBuilder.new(@view)
+        @view.capture(group_builder, &block)
+
+        @parts << @view.render("components/dropdown_menu/group", **options) do
+          group_builder.to_html
+        end
+      end
+
+      # Generates the final HTML
+      def to_html
+        @view.safe_join(@parts)
+      end
+
+      private
+
+      def build_item_content(label, icon)
+        parts = []
+        parts << @view.icon_for(icon) if icon && @view.respond_to?(:icon_for)
+        parts << label
+        @view.safe_join(parts)
+      end
+    end
+
+    # Builder for individual menu items (supports shortcuts)
+    class DropdownMenuItemBuilder
+      attr_reader :shortcut_html
+
+      def initialize(view_context)
+        @view = view_context
+        @shortcut_html = nil
+      end
+
+      # Adds a keyboard shortcut
+      #
+      # @param text [String] Shortcut text
+      def shortcut(text)
+        @shortcut_html = @view.render("components/dropdown_menu/shortcut", text: text)
+      end
+    end
+  end
+end

data/app/helpers/maquina_components/empty_helper.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module MaquinaComponents
+  # Empty Helper
+  #
+  # Provides convenient methods for creating empty state components.
+  #
+  # @example Simple empty state
+  #   <%= empty_state title: "No projects", description: "Get started by creating one.", icon: :folder_open %>
+  #
+  # @example With action button
+  #   <%= empty_state title: "No projects", icon: :folder_open do %>
+  #     <%= link_to "Create Project", new_project_path, data: { component: "button", variant: "primary" } %>
+  #   <% end %>
+  #
+  # @example Full control with partials
+  #   <%= render "components/empty", variant: :outline do %>
+  #     <%= render "components/empty/header" do %>
+  #       <%= render "components/empty/media", icon: :search %>
+  #       <%= render "components/empty/title", text: "No results" %>
+  #     <% end %>
+  #   <% end %>
+  #
+  module EmptyHelper
+    # Renders an empty state component with a simple API
+    #
+    # @param title [String] The title text
+    # @param description [String, nil] Optional description text
+    # @param icon [Symbol, nil] Icon name (uses icon_for helper)
+    # @param variant [Symbol] Visual style (:default, :outline)
+    # @param size [Symbol] Size variant (:default, :compact)
+    # @param css_classes [String] Additional CSS classes
+    # @param html_options [Hash] Additional HTML attributes
+    # @yield Optional block for action content (buttons, links)
+    # @return [String] Rendered HTML
+    def empty_state(title:, description: nil, icon: nil, variant: :default, size: :default, css_classes: "", **html_options, &block)
+      render "components/empty", variant: variant, size: size, css_classes: css_classes, **html_options do
+        parts = []
+
+        # Build header
+        header_content = []
+        header_content << render("components/empty/media", icon: icon) if icon
+        header_content << render("components/empty/title", text: title)
+        header_content << render("components/empty/description", text: description) if description
+
+        parts << render("components/empty/header") { safe_join(header_content) }
+
+        # Add content/actions if block given
+        if block
+          parts << render("components/empty/content") { capture(&block) }
+        end
+
+        safe_join(parts)
+      end
+    end
+
+    # Renders an empty state for search results
+    #
+    # @param query [String, nil] The search query (for display)
+    # @param reset_path [String, nil] Path to reset/clear search
+    # @param size [Symbol] Size variant
+    # @return [String] Rendered HTML
+    def empty_search_state(query: nil, reset_path: nil, size: :default)
+      description = if query.present?
+        "No results found for \"#{query}\". Try a different search term."
+      else
+        "No results found. Try adjusting your search."
+      end
+
+      empty_state(
+        title: "No results",
+        description: description,
+        icon: :search,
+        size: size
+      ) do
+        if reset_path
+          link_to "Clear search", reset_path, data: {component: "button", variant: "outline", size: "sm"}
+        end
+      end
+    end
+
+    # Renders an empty state for lists/tables
+    #
+    # @param resource_name [String] Name of the resource (e.g., "projects", "users")
+    # @param new_path [String, nil] Path to create new resource
+    # @param icon [Symbol] Icon to display
+    # @param size [Symbol] Size variant
+    # @return [String] Rendered HTML
+    def empty_list_state(resource_name:, new_path: nil, icon: :folder_open, size: :default)
+      empty_state(
+        title: "No #{resource_name} yet",
+        description: "Get started by creating your first #{resource_name.singularize}.",
+        icon: icon,
+        size: size
+      ) do
+        if new_path
+          link_to "Create #{resource_name.singularize.titleize}", new_path, data: {component: "button", variant: "primary"}
+        end
+      end
+    end
+  end
+end