maquina-components 0.2.0 → 0.3.1

data/app/helpers/maquina_components/calendar_helper.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module MaquinaComponents
+  # Calendar Helper
+  #
+  # Provides utility methods for working with calendar and date picker data.
+  #
+  # @example Generate month data
+  #   calendar_month_data(Date.current, :sunday)
+  #
+  # @example Check if date is in range
+  #   calendar_date_in_range?(date, start_date, end_date)
+  #
+  module CalendarHelper
+    # Generate calendar month data
+    #
+    # @param date [Date] Any date within the target month
+    # @param week_starts_on [Symbol] :sunday or :monday
+    # @return [Hash] Month metadata and weeks array
+    def calendar_month_data(date, week_starts_on = :sunday)
+      first_of_month = date.beginning_of_month
+      last_of_month = date.end_of_month
+
+      # Calculate start of calendar grid
+      week_start = (week_starts_on == :monday) ? 1 : 0
+      days_before = (first_of_month.wday - week_start) % 7
+      calendar_start = first_of_month - days_before.days
+
+      # Calculate end of calendar grid (6 weeks max)
+      total_days = days_before + last_of_month.day
+      weeks_needed = (total_days / 7.0).ceil
+      weeks_needed = [weeks_needed, 6].min
+      calendar_end = calendar_start + (weeks_needed * 7 - 1).days
+
+      # Build weeks array
+      weeks = (calendar_start..calendar_end).each_slice(7).to_a
+
+      {
+        month: date.month,
+        year: date.year,
+        first_of_month: first_of_month,
+        last_of_month: last_of_month,
+        weeks: weeks,
+        week_starts_on: week_starts_on
+      }
+    end
+
+    # Format month name with year
+    #
+    # @param date [Date] Any date within the target month
+    # @param format [Symbol] :long (%B %Y) or :short (%b %Y)
+    # @return [String] Formatted month name
+    def calendar_month_name(date, format = :long)
+      case format
+      when :short
+        I18n.l(date, format: "%b %Y")
+      else
+        I18n.l(date, format: "%B %Y")
+      end
+    end
+
+    # Check if a date falls within a range
+    #
+    # @param date [Date] The date to check
+    # @param start_date [Date, nil] Range start (inclusive)
+    # @param end_date [Date, nil] Range end (inclusive)
+    # @return [Boolean]
+    def calendar_date_in_range?(date, start_date, end_date)
+      return false unless start_date && end_date
+      date.between?(start_date, end_date)
+    end
+
+    # Generate data attributes hash for calendar
+    #
+    # @param mode [Symbol] :single or :range
+    # @param selected [Date, String, nil] Selected date
+    # @param selected_end [Date, String, nil] End date for range
+    # @param month [Integer, nil] Display month
+    # @param year [Integer, nil] Display year
+    # @return [Hash] Data attributes for use with content_tag
+    def calendar_data_attrs(mode: :single, selected: nil, selected_end: nil, month: nil, year: nil)
+      selected_str = case selected
+      when Date, Time, DateTime then selected.to_date.iso8601
+      when String then selected
+      end
+
+      selected_end_str = case selected_end
+      when Date, Time, DateTime then selected_end.to_date.iso8601
+      when String then selected_end
+      end
+
+      display_date = selected_str ? Date.parse(selected_str) : Date.current
+      display_month = month || display_date.month
+      display_year = year || display_date.year
+
+      {
+        data: {
+          controller: "calendar",
+          component: "calendar",
+          "calendar-mode-value": mode,
+          "calendar-month-value": display_month,
+          "calendar-year-value": display_year,
+          "calendar-selected-value": selected_str,
+          "calendar-selected-end-value": selected_end_str
+        }.compact
+      }
+    end
+
+    # Get weekday names based on week start
+    #
+    # @param week_starts_on [Symbol] :sunday or :monday
+    # @param format [Symbol] :short (Mo, Tu) or :narrow (M, T) or :long (Monday)
+    # @return [Array<String>]
+    def calendar_weekday_names(week_starts_on = :sunday, format = :short)
+      names = case format
+      when :narrow
+        %w[S M T W T F S]
+      when :long
+        I18n.t("date.day_names")
+      else
+        %w[Su Mo Tu We Th Fr Sa]
+      end
+
+      (week_starts_on == :monday) ? names.rotate(1) : names
+    end
+
+    # Generate data attributes hash for date picker
+    #
+    # @param mode [Symbol] :single or :range
+    # @param selected [Date, String, nil] Selected date
+    # @param selected_end [Date, String, nil] End date for range
+    # @return [Hash] Data attributes for use with content_tag
+    def date_picker_data_attrs(mode: :single, selected: nil, selected_end: nil)
+      selected_str = case selected
+      when Date, Time, DateTime then selected.to_date.iso8601
+      when String then selected
+      end
+
+      selected_end_str = case selected_end
+      when Date, Time, DateTime then selected_end.to_date.iso8601
+      when String then selected_end
+      end
+
+      {
+        data: {
+          controller: "date-picker",
+          component: "date-picker",
+          "date-picker-mode-value": mode,
+          "date-picker-selected-value": selected_str,
+          "date-picker-selected-end-value": selected_end_str
+        }.compact
+      }
+    end
+
+    # Format date for display in date picker
+    #
+    # @param date [Date, String, nil] Date to format
+    # @param format [Symbol] :short, :long, or :full
+    # @return [String, nil]
+    def date_picker_format(date, format = :long)
+      return nil unless date
+
+      date = Date.parse(date) if date.is_a?(String)
+
+      case format
+      when :short
+        I18n.l(date, format: :short)
+      when :full
+        I18n.l(date, format: :long)
+      else
+        I18n.l(date, format: :long)
+      end
+    rescue ArgumentError
+      nil
+    end
+
+    # Format date range for display
+    #
+    # @param start_date [Date, String, nil] Start date
+    # @param end_date [Date, String, nil] End date
+    # @param format [Symbol] :short or :long
+    # @return [String, nil]
+    def date_picker_format_range(start_date, end_date, format = :short)
+      start_str = date_picker_format(start_date, format)
+      end_str = date_picker_format(end_date, format)
+
+      return nil unless start_str
+
+      if end_str
+        "#{start_str} - #{end_str}"
+      else
+        "#{start_str} - ..."
+      end
+    end
+  end
+end

data/app/helpers/maquina_components/combobox_helper.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module MaquinaComponents
+  # Combobox Helper
+  #
+  # Provides a builder pattern for creating combobox components with a clean API.
+  #
+  # @example Basic usage
+  #   <%= combobox placeholder: "Select framework..." do |cb| %>
+  #     <% cb.trigger %>
+  #     <% cb.content do %>
+  #       <% cb.input placeholder: "Search..." %>
+  #       <% cb.list do %>
+  #         <% cb.option value: "nextjs" do %>Next.js<% end %>
+  #         <% cb.option value: "remix" do %>Remix<% end %>
+  #       <% end %>
+  #       <% cb.empty %>
+  #     <% end %>
+  #   <% end %>
+  #
+  # @example Simple data-driven combobox
+  #   <%= combobox_simple placeholder: "Select framework...",
+  #                       options: [
+  #                         { value: "nextjs", label: "Next.js" },
+  #                         { value: "remix", label: "Remix" }
+  #                       ] %>
+  #
+  # @example With groups
+  #   <%= combobox placeholder: "Select..." do |cb| %>
+  #     <% cb.trigger %>
+  #     <% cb.content do %>
+  #       <% cb.input %>
+  #       <% cb.list do %>
+  #         <% cb.group do %>
+  #           <% cb.label "Frontend" %>
+  #           <% cb.option value: "react" do %>React<% end %>
+  #           <% cb.option value: "vue" do %>Vue<% end %>
+  #         <% end %>
+  #         <% cb.separator %>
+  #         <% cb.group do %>
+  #           <% cb.label "Backend" %>
+  #           <% cb.option value: "rails" do %>Rails<% end %>
+  #         <% end %>
+  #       <% end %>
+  #       <% cb.empty %>
+  #     <% end %>
+  #   <% end %>
+  #
+  module ComboboxHelper
+    # Renders a combobox using the builder pattern
+    #
+    # @param id [String, nil] Explicit ID for the combobox
+    # @param name [String, nil] Form field name
+    # @param value [String, nil] Currently selected value
+    # @param placeholder [String] Placeholder text
+    # @param css_classes [String] Additional CSS classes
+    # @param html_options [Hash] Additional HTML attributes
+    # @yield [ComboboxBuilder] Builder instance for constructing the combobox
+    # @return [String] Rendered HTML
+    def combobox(id: nil, name: nil, value: nil, placeholder: "Select...", css_classes: "", **html_options, &block)
+      builder = ComboboxBuilder.new(self, placeholder: placeholder)
+      combobox_id = id || "combobox-#{SecureRandom.hex(4)}"
+      builder.combobox_id = combobox_id
+
+      capture(builder, &block)
+
+      render "components/combobox",
+        id: combobox_id,
+        name: name,
+        value: value,
+        placeholder: placeholder,
+        css_classes: css_classes,
+        **html_options do |_id|
+        builder.to_html
+      end
+    end
+
+    # Renders a simple combobox from data
+    #
+    # @param options [Array<Hash>] Array of option configurations with :value and :label keys
+    # @param placeholder [String] Placeholder text
+    # @param search_placeholder [String] Search input placeholder
+    # @param empty_text [String] Text shown when no results
+    # @param value [String, nil] Currently selected value
+    # @param name [String, nil] Form field name
+    # @param trigger_options [Hash] Options for the trigger button
+    # @param content_options [Hash] Options for the content container
+    # @return [String] Rendered HTML
+    def combobox_simple(
+      options:,
+      placeholder: "Select...",
+      search_placeholder: "Search...",
+      empty_text: "No results found.",
+      value: nil,
+      name: nil,
+      trigger_options: {},
+      content_options: {}
+    )
+      combobox(placeholder: placeholder, value: value, name: name) do |cb|
+        cb.trigger(**trigger_options)
+
+        cb.content(**content_options) do
+          cb.input(placeholder: search_placeholder)
+          cb.list do
+            options.each do |opt|
+              selected = value.present? && opt[:value].to_s == value.to_s
+              cb.option(value: opt[:value], selected: selected, disabled: opt[:disabled]) do
+                opt[:label] || opt[:value]
+              end
+            end
+          end
+          cb.empty(text: empty_text)
+        end
+      end
+    end
+
+    # Builder class for constructing comboboxes
+    class ComboboxBuilder
+      attr_accessor :combobox_id
+
+      def initialize(view_context, placeholder:)
+        @view = view_context
+        @placeholder = placeholder
+        @parts = []
+      end
+
+      # Defines the trigger button
+      #
+      # @param variant [Symbol] Button variant
+      # @param size [Symbol] Button size
+      # @param options [Hash] Additional options
+      def trigger(variant: :outline, size: :default, **options)
+        @parts << @view.render(
+          "components/combobox/trigger",
+          for_id: combobox_id,
+          placeholder: @placeholder,
+          variant: variant,
+          size: size,
+          **options
+        )
+      end
+
+      # Defines the content popover
+      #
+      # @param align [Symbol] Horizontal alignment
+      # @param width [Symbol] Width preset
+      # @param options [Hash] Additional options
+      # @yield Block containing combobox content
+      def content(align: :start, width: :default, **options, &block)
+        content_builder = ComboboxContentBuilder.new(@view)
+        @view.capture(content_builder, &block)
+
+        @parts << @view.render(
+          "components/combobox/content",
+          id: combobox_id,
+          align: align,
+          width: width,
+          **options
+        ) { content_builder.to_html }
+      end
+
+      # Shortcut to add input directly (delegates to content builder)
+      def input(placeholder: "Search...", **options)
+        @current_content_builder&.input(placeholder: placeholder, **options)
+      end
+
+      # Shortcut to add list directly (delegates to content builder)
+      def list(**options, &block)
+        @current_content_builder&.list(**options, &block)
+      end
+
+      # Shortcut to add empty directly (delegates to content builder)
+      def empty(text: "No results found.", **options)
+        @current_content_builder&.empty(text: text, **options)
+      end
+
+      # Generates the final HTML
+      def to_html
+        @view.safe_join(@parts)
+      end
+    end
+
+    # Builder for combobox content
+    class ComboboxContentBuilder
+      def initialize(view_context)
+        @view = view_context
+        @parts = []
+      end
+
+      # Adds the search input
+      #
+      # @param placeholder [String] Input placeholder
+      # @param options [Hash] Additional options
+      def input(placeholder: "Search...", **options)
+        @parts << @view.render(
+          "components/combobox/input",
+          placeholder: placeholder,
+          **options
+        )
+      end
+
+      # Adds the options list container
+      #
+      # @param options [Hash] Additional options
+      # @yield Block containing options
+      def list(**options, &block)
+        list_builder = ComboboxListBuilder.new(@view)
+        @view.capture(list_builder, &block)
+
+        @parts << @view.render(
+          "components/combobox/list",
+          **options
+        ) { list_builder.to_html }
+      end
+
+      # Adds the empty state
+      #
+      # @param text [String] Empty state text
+      # @param options [Hash] Additional options
+      def empty(text: "No results found.", **options)
+        @parts << @view.render(
+          "components/combobox/empty",
+          text: text,
+          **options
+        )
+      end
+
+      # Generates the final HTML
+      def to_html
+        @view.safe_join(@parts)
+      end
+    end
+
+    # Builder for combobox list content
+    class ComboboxListBuilder
+      def initialize(view_context)
+        @view = view_context
+        @parts = []
+      end
+
+      # Adds an option
+      #
+      # @param value [String] Option value
+      # @param selected [Boolean] Whether selected
+      # @param disabled [Boolean] Whether disabled
+      # @param options [Hash] Additional options
+      # @yield Block for option content
+      def option(value:, selected: false, disabled: false, **options, &block)
+        content = @view.capture(&block) if block
+        @parts << @view.render(
+          "components/combobox/option",
+          value: value,
+          selected: selected,
+          disabled: disabled,
+          **options
+        ) { content }
+      end
+
+      # Adds a group
+      #
+      # @param options [Hash] Additional options
+      # @yield Block containing group items
+      def group(**options, &block)
+        group_builder = ComboboxListBuilder.new(@view)
+        @view.capture(group_builder, &block)
+
+        @parts << @view.render(
+          "components/combobox/group",
+          **options
+        ) { group_builder.to_html }
+      end
+
+      # Adds a label
+      #
+      # @param text [String, nil] Label text
+      # @param options [Hash] Additional options
+      # @yield Optional block for custom content
+      def label(text = nil, **options, &block)
+        @parts << @view.render(
+          "components/combobox/label",
+          text: text,
+          **options,
+          &block
+        )
+      end
+
+      # Adds a separator
+      #
+      # @param options [Hash] Additional options
+      def separator(**options)
+        @parts << @view.render("components/combobox/separator", **options)
+      end
+
+      # Generates the final HTML
+      def to_html
+        @view.safe_join(@parts)
+      end
+    end
+  end
+end