odt-ui-rails 2.2.0 → 2.2.2

data/lib/generators/odt/templates/odt_ui.rbs

@@ -0,0 +1,302 @@
+module OdtUi
+  VERSION: String
+
+  module Helper
+    type button_variant = :filled | :frosted | :capsule | :ghost | :light | :outline | :outlined | :subtle | String
+    type button_color = :primary | :secondary | :surface | :muted | :inverse | :success | :warning | :danger | :info | :neutral | String
+    type button_size = :xs | :sm | :md | :lg | :xl | String
+    type radius_size = :none | :xs | :sm | :md | :lg | :xl | :"2xl" | :"3xl" | :"4xl" | :full | Symbol | String
+    type shadow_size = :none | :card | :dropdown | :modal | :popover | Symbol | String
+
+    type badge_variant = :subtle | :filled | :outlined | :outline | String
+    type badge_color = :primary | :secondary | :success | :warning | :danger | :info | :neutral | String
+    type badge_size = :sm | :md | String
+
+    type card_variant = :elevated | :outlined | :subtle | :muted | :ghost | :frosted | String
+    type card_background = :base | :surface | :surface_elevated | :surface_muted | :surface_subtle | :gradient_primary | :gradient_secondary | :gradient_vibrant | :gradient_hero | :frosted | :frosted_muted | :frosted_subtle | :frosted_gradient_primary | :frosted_gradient_secondary | :transparent | Symbol | String
+    type card_border = :none | :muted | :base | :strong | :primary | :secondary | :danger | :success | bool | Symbol | String
+    type card_padding = :none | :xs | :sm | :md | :lg | :xl | :"2xl" | Symbol | String
+    type card_tag = :div | :article | :section | :aside | :main | Symbol | String
+
+    type alert_variant = :success | :warning | :danger | :info | String
+    type heading_tag = :h1 | :h2 | :h3 | :h4 | :h5 | :h6 | String
+    type heading_size = :"5xl" | :"4xl" | :"3xl" | :"2xl" | :xl | :lg | Symbol | String
+    type font_weight = :light | :normal | :medium | :semibold | :bold | :extrabold | Symbol | String
+    type typography_color = :strong | :default | :muted | :subtle | :disabled | :primary | :secondary | :success | :warning | :danger | :info | Symbol | String
+
+    type text_tag = :p | :span | :div | :label | :small | Symbol | String
+    type text_size = :xs | :sm | :base | :lg | :xl | :"2xl" | Symbol | String
+
+    type avatar_size = :xs | :sm | :md | :lg | :xl | :"2xl" | String
+    type avatar_color = :secondary | :primary | :neutral | String
+
+    type input_variant = :outlined | :filled | :frosted | String
+    type input_size = :sm | :md | :lg | String
+    type input_resize = :none | :vertical | :horizontal | :both | String
+    type checkbox_color = :primary | :secondary | :success | :warning | :danger | :dark | :neutral | String
+    type checkbox_size = :sm | :md | :lg | String
+
+    # Renders an ODT Button component.
+    def odt_button: (
+      ?String? text,
+      ?variant: button_variant,
+      ?color: button_color,
+      ?size: button_size,
+      ?radius: radius_size?,
+      ?shadow: shadow_size?,
+      ?icon_only: bool,
+      ?full_width: bool,
+      ?loading: bool,
+      ?disabled: bool,
+      ?href: String?,
+      ?icon: String?,
+      ?right_icon: String?,
+      ?type: String,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Badge component.
+    def odt_badge: (
+      ?String? text,
+      ?variant: badge_variant,
+      ?color: badge_color,
+      ?size: badge_size,
+      ?radius: radius_size?,
+      ?dot: bool,
+      ?icon: String?,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Card component.
+    def odt_card: (
+      ?title: String?,
+      ?subtitle: String?,
+      ?variant: card_variant,
+      ?background: card_background?,
+      ?border: card_border?,
+      ?shadow: shadow_size?,
+      ?radius: radius_size?,
+      ?padding: card_padding?,
+      ?hoverable: bool,
+      ?hover: bool,
+      ?as: card_tag,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Alert banner.
+    def odt_alert: (
+      ?String? message,
+      ?variant: alert_variant,
+      ?icon: String?,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Heading element.
+    def odt_heading: (
+      ?String? text,
+      ?as: heading_tag,
+      ?size: heading_size?,
+      ?weight: font_weight?,
+      ?color: typography_color?,
+      ?truncate: bool,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders styled body text.
+    def odt_text: (
+      ?String? text,
+      ?as: text_tag,
+      ?size: text_size?,
+      ?weight: font_weight?,
+      ?color: typography_color?,
+      ?truncate: bool,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Avatar element.
+    def odt_avatar: (
+      ?name: String?,
+      ?src: String?,
+      ?size: avatar_size,
+      ?color: avatar_color,
+      ?icon: String,
+      ?fallback: String?,
+      **untyped
+    ) -> untyped
+
+    # Renders a styled input field.
+    def odt_input: (
+      ?label: String?,
+      ?variant: input_variant,
+      ?size: input_size,
+      ?radius: radius_size?,
+      ?type: String,
+      ?placeholder: String?,
+      ?error: String?,
+      ?helper: String?,
+      ?helper_text: String?,
+      ?success: String?,
+      ?left_icon: String?,
+      ?right_icon: String?,
+      ?prefix: String?,
+      ?suffix: String?,
+      ?addon_before: String?,
+      ?addon_after: String?,
+      ?disabled: bool,
+      ?full_width: bool,
+      **untyped
+    ) -> untyped
+
+    # Renders a styled textarea field.
+    def odt_textarea: (
+      ?label: String?,
+      ?variant: input_variant,
+      ?size: input_size,
+      ?radius: radius_size?,
+      ?rows: Integer,
+      ?resize: input_resize,
+      ?error: String?,
+      ?helper: String?,
+      ?helper_text: String?,
+      ?success: String?,
+      ?disabled: bool,
+      ?full_width: bool,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders a styled native <select> dropdown.
+    def odt_select: (
+      ?label: String?,
+      ?options: untyped,
+      ?variant: input_variant,
+      ?size: input_size,
+      ?radius: radius_size?,
+      ?prompt: String?,
+      ?error: String?,
+      ?helper: String?,
+      ?helper_text: String?,
+      ?success: String?,
+      ?disabled: bool,
+      ?full_width: bool,
+      **untyped
+    ) -> untyped
+
+    # Renders a styled checkbox.
+    def odt_checkbox: (
+      ?label: String?,
+      ?description: String?,
+      ?checked: bool,
+      ?color: checkbox_color,
+      ?size: checkbox_size,
+      ?radius: radius_size?,
+      ?disabled: bool,
+      ?error: String?,
+      **untyped
+    ) -> untyped
+
+    # Renders a styled radio button.
+    def odt_radio: (
+      ?label: String?,
+      ?description: String?,
+      ?checked: bool,
+      ?color: checkbox_color,
+      ?size: checkbox_size,
+      ?disabled: bool,
+      ?error: String?,
+      **untyped
+    ) -> untyped
+
+    # Renders a form field wrapper.
+    def odt_form_group: (
+      ?label: String?,
+      ?error: String?,
+      ?helper: String?,
+      ?helper_text: String?,
+      ?success: String?,
+      ?required: bool,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    type toaster_position = :top_right | :top_center | :top_left | :bottom_right | :bottom_center | :bottom_left | Symbol | String
+    type toast_variant = :success | :warning | :danger | :error | :info | :loading | :frosted | Symbol | String
+
+    # Renders an ODT Toaster viewport container.
+    def odt_toaster: (
+      ?position: toaster_position,
+      ?id: String,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders a single ODT Toast card.
+    def odt_toast: (
+      ?String? message,
+      ?title: String?,
+      ?variant: toast_variant,
+      ?icon: String?,
+      ?duration: Integer,
+      ?dismissible: bool,
+      ?radius: radius_size?,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders active flash messages as ODT Toasts.
+    def odt_flash_toasts: (
+      ?untyped flash_hash,
+      ?duration: Integer
+    ) -> untyped
+
+    # Generates a Turbo Stream action for a toast.
+    def odt_toast_stream: (
+      ?String? message,
+      ?title: String?,
+      ?variant: toast_variant,
+      ?target: String,
+      ?action: Symbol | String,
+      ?duration: Integer,
+      **untyped
+    ) -> untyped
+
+    type modal_size = :sm | :md | :lg | :xl | :full | Symbol | String
+
+    # Renders an ODT Modal dialog container.
+    def odt_modal: (
+      ?id: String?,
+      ?title: String?,
+      ?subtitle: String?,
+      ?size: modal_size,
+      ?radius: radius_size?,
+      ?dismissible: bool,
+      ?open: bool,
+      ?prevent_backdrop_close: bool,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Modal Header subcomponent.
+    def odt_modal_header: (
+      ?title: String?,
+      ?subtitle: String?,
+      ?dismissible: bool,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Modal Body subcomponent.
+    def odt_modal_body: (
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Modal Footer subcomponent.
+    def odt_modal_footer: (
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+  end
+end
+
+module ActionView
+  class Base
+    include OdtUi::Helper
+  end
+
+  module Helpers
+    include OdtUi::Helper
+  end
+end

data/lib/odt_ui/helper.rb

@@ -677,6 +677,271 @@ module OdtUi
       end
     end
 
+    # Renders an ODT Toaster viewport container.
+    #
+    # @param position [:top_right, :top_center, :top_left, :bottom_right, :bottom_center, :bottom_left]
+    # @param id [String] Element ID for Turbo Stream targeting (default: "odt-toasts")
+    # @return [ActiveSupport::SafeBuffer]
+    def odt_toaster(position: :top_right, id: "odt-toasts", **html_options, &block)
+      pos_key = position.to_s.tr("_", "-")
+      classes = [
+        "odt-toaster",
+        "odt-toaster--#{pos_key}",
+        html_options.delete(:class)
+      ]
+
+      opts = html_options.merge(
+        id: id,
+        class: classes.compact.reject(&:blank?).join(" "),
+        role: "region",
+        aria: { live: "polite" }
+      )
+
+      inner_content = block_given? ? capture(&block) : nil
+      tag.div(inner_content, **opts)
+    end
+
+    # Renders a single ODT Toast card with Stimulus controller.
+    #
+    # @param message [String, nil]
+    # @param title [String, nil]
+    # @param variant [:success, :warning, :danger, :error, :info, :loading, :frosted]
+    # @param icon [String, nil]
+    # @param duration [Integer] Auto-dismiss duration in milliseconds (0 to disable)
+    # @param dismissible [Boolean] Whether to display close button
+    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full, nil]
+    # @return [ActiveSupport::SafeBuffer]
+    def odt_toast(message = nil, title: nil, variant: :success, icon: nil, duration: 4000, dismissible: true, radius: nil, **html_options, &block)
+      variant_key = variant.to_sym == :error ? :danger : variant.to_sym
+      default_icons = {
+        success: "fa-solid fa-circle-check",
+        warning: "fa-solid fa-triangle-exclamation",
+        danger:  "fa-solid fa-circle-xmark",
+        info:    "fa-solid fa-circle-info",
+        loading: "fa-solid fa-spinner"
+      }
+
+      icon_name = icon || default_icons[variant_key] || default_icons[:info]
+
+      classes = [
+        "odt-toast",
+        "odt-toast--#{variant_key.to_s.tr('_', '-')}"
+      ]
+      classes << "odt-radius-#{radius.to_s.tr('_', '-')}" if radius.present?
+      classes << html_options.delete(:class)
+
+      data_attrs = {
+        controller: "odt-toast",
+        odt_toast_duration_value: duration,
+        action: "mouseenter->odt-toast#pauseTimer mouseleave->odt-toast#resumeTimer"
+      }.merge(html_options.delete(:data) || {})
+
+      opts = html_options.merge(
+        class: classes.compact.reject(&:blank?).join(" "),
+        role: "status",
+        data: data_attrs
+      )
+
+      parts = []
+      if icon_name.present?
+        icon_classes = ["odt-toast__icon", "odt-toast__icon--#{variant_key}"]
+        parts << tag.span(render_icon_element(icon_name), class: icon_classes.join(" "))
+      end
+
+      body_content = block_given? ? capture(&block) : message
+
+      parts << tag.div(class: "odt-toast__content") do
+        c_parts = []
+        c_parts << tag.p(title, class: "odt-toast__title") if title.present?
+        c_parts << tag.p(body_content, class: "odt-toast__message") if body_content.present?
+        safe_join(c_parts)
+      end
+
+      if dismissible
+        parts << tag.button(
+          "×".html_safe,
+          type: "button",
+          class: "odt-toast__close",
+          aria: { label: "Close" },
+          data: { action: "click->odt-toast#dismiss" }
+        )
+      end
+
+      inner_content = safe_join(parts.compact)
+      tag.div(inner_content, **opts)
+    end
+
+    # Renders all active flash messages as ODT Toasts.
+    #
+    # @param flash_hash [ActionDispatch::Flash::FlashHash, Hash] Flash messages hash (default: flash)
+    # @param duration [Integer] Auto-dismiss duration in milliseconds
+    # @return [ActiveSupport::SafeBuffer]
+    def odt_flash_toasts(flash_hash = flash, duration: 4000)
+      return "".html_safe if flash_hash.blank?
+
+      toasts = []
+      flash_hash.each do |type, message|
+        next if message.blank?
+
+        variant = case type.to_sym
+        when :notice, :success
+          :success
+        when :alert, :error, :danger
+          :danger
+        when :warning
+          :warning
+        else
+          :info
+        end
+
+        toasts << odt_toast(message, variant: variant, duration: duration)
+      end
+
+      safe_join(toasts)
+    end
+
+    # Generates a Turbo Stream action to render a toast asynchronously.
+    #
+    # @param message [String, nil]
+    # @param title [String, nil]
+    # @param variant [:success, :warning, :danger, :error, :info]
+    # @param target [String] Target container ID (default: "odt-toasts")
+    # @param action [:append, :prepend] Turbo stream action (default: :append)
+    # @param duration [Integer] Auto-dismiss duration in ms (default: 4000)
+    # @return [ActiveSupport::SafeBuffer]
+    def odt_toast_stream(message = nil, title: nil, variant: :success, target: "odt-toasts", action: :append, duration: 4000, **options)
+      toast_html = odt_toast(message, title: title, variant: variant, duration: duration, **options)
+
+      if respond_to?(:turbo_stream)
+        turbo_stream.public_send(action, target, toast_html)
+      else
+        tag.public_send("turbo-stream", action: action, target: target) do
+          tag.template(toast_html)
+        end
+      end
+    end
+
+    # Renders an ODT Modal dialog container with Stimulus controller.
+    #
+    # @param id [String, nil] Unique HTML ID of the modal
+    # @param title [String, nil] Header title text
+    # @param subtitle [String, nil] Header subtitle text
+    # @param size [:sm, :md, :lg, :xl, :full] Dialog width size (default: :md)
+    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full, nil]
+    # @param dismissible [Boolean] Whether to render the header close button (default: true)
+    # @param open [Boolean] Whether modal is initially open (default: false)
+    # @param prevent_backdrop_close [Boolean] Prevent closing when clicking overlay (default: false)
+    # @return [ActiveSupport::SafeBuffer]
+    def odt_modal(id: nil, title: nil, subtitle: nil, size: :md, radius: :"2xl", dismissible: true, open: false, prevent_backdrop_close: false, **html_options, &block)
+      size_key = size.to_s.tr("_", "-")
+      radius_key = radius.to_s.tr("_", "-")
+
+      overlay_classes = [
+        "odt-modal-overlay",
+        ("hidden" unless open),
+        html_options.delete(:class)
+      ]
+
+      data_attrs = {
+        controller: "odt-modal",
+        odt_modal_open_value: open,
+        odt_modal_prevent_backdrop_close_value: prevent_backdrop_close,
+        action: "click->odt-modal#backdropClose keydown.esc@window->odt-modal#close"
+      }.merge(html_options.delete(:data) || {})
+
+      opts = html_options.merge(
+        id: id,
+        class: overlay_classes.compact.reject(&:blank?).join(" "),
+        role: "dialog",
+        aria: { modal: "true", hidden: (!open).to_s },
+        data: data_attrs
+      )
+
+      modal_classes = [
+        "odt-modal",
+        "odt-modal--#{size_key}",
+        "odt-radius-#{radius_key}"
+      ]
+
+      body_content = block_given? ? capture(&block) : nil
+
+      tag.div(**opts) do
+        tag.div(class: modal_classes.join(" "), data: { odt_modal_target: "dialog" }) do
+          parts = []
+          if title.present? || subtitle.present? || dismissible
+            parts << odt_modal_header(title: title, subtitle: subtitle, dismissible: dismissible)
+          end
+
+          if body_content.present?
+            if body_content.include?("odt-modal__body") || body_content.include?("odt-modal__header")
+              parts << body_content
+            else
+              parts << tag.div(body_content, class: "odt-modal__body")
+            end
+          end
+
+          safe_join(parts)
+        end
+      end
+    end
+
+    # Renders an ODT Modal Header subcomponent.
+    #
+    # @param title [String, nil]
+    # @param subtitle [String, nil]
+    # @param dismissible [Boolean]
+    # @return [ActiveSupport::SafeBuffer]
+    def odt_modal_header(title: nil, subtitle: nil, dismissible: true, **html_options, &block)
+      classes = ["odt-modal__header", html_options.delete(:class)]
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
+
+      tag.div(**opts) do
+        parts = []
+        if block_given?
+          parts << capture(&block)
+        else
+          parts << tag.div(class: "odt-modal__header-content") do
+            c_parts = []
+            c_parts << tag.h3(title, class: "odt-modal__title") if title.present?
+            c_parts << tag.p(subtitle, class: "odt-modal__subtitle") if subtitle.present?
+            safe_join(c_parts)
+          end
+        end
+
+        if dismissible
+          parts << tag.button(
+            "×".html_safe,
+            type: "button",
+            class: "odt-modal__close",
+            aria: { label: "Close" },
+            data: { action: "click->odt-modal#close" }
+          )
+        end
+
+        safe_join(parts)
+      end
+    end
+
+    # Renders an ODT Modal Body subcomponent.
+    #
+    # @return [ActiveSupport::SafeBuffer]
+    def odt_modal_body(**html_options, &block)
+      classes = ["odt-modal__body", html_options.delete(:class)]
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
+      content = block_given? ? capture(&block) : nil
+      tag.div(content, **opts)
+    end
+
+    # Renders an ODT Modal Footer subcomponent.
+    #
+    # @return [ActiveSupport::SafeBuffer]
+    def odt_modal_footer(**html_options, &block)
+      classes = ["odt-modal__footer", html_options.delete(:class)]
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
+      content = block_given? ? capture(&block) : nil
+      tag.div(content, **opts)
+    end
+
     private
 
     # Normalizes button variant key with backwards compatibility

data/lib/odt_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OdtUi
-  VERSION = "2.2.0"
+  VERSION = "2.2.2"
 end

data/sig/odt_ui.rbs

@@ -216,6 +216,78 @@ module OdtUi
       ?required: bool,
       **untyped
     ) ?{ () -> untyped } -> untyped
+
+    type toaster_position = :top_right | :top_center | :top_left | :bottom_right | :bottom_center | :bottom_left | Symbol | String
+    type toast_variant = :success | :warning | :danger | :error | :info | :loading | :frosted | Symbol | String
+
+    # Renders an ODT Toaster viewport container.
+    def odt_toaster: (
+      ?position: toaster_position,
+      ?id: String,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders a single ODT Toast card.
+    def odt_toast: (
+      ?String? message,
+      ?title: String?,
+      ?variant: toast_variant,
+      ?icon: String?,
+      ?duration: Integer,
+      ?dismissible: bool,
+      ?radius: radius_size?,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders active flash messages as ODT Toasts.
+    def odt_flash_toasts: (
+      ?untyped flash_hash,
+      ?duration: Integer
+    ) -> untyped
+
+    # Generates a Turbo Stream action for a toast.
+    def odt_toast_stream: (
+      ?String? message,
+      ?title: String?,
+      ?variant: toast_variant,
+      ?target: String,
+      ?action: Symbol | String,
+      ?duration: Integer,
+      **untyped
+    ) -> untyped
+
+    type modal_size = :sm | :md | :lg | :xl | :full | Symbol | String
+
+    # Renders an ODT Modal dialog container.
+    def odt_modal: (
+      ?id: String?,
+      ?title: String?,
+      ?subtitle: String?,
+      ?size: modal_size,
+      ?radius: radius_size?,
+      ?dismissible: bool,
+      ?open: bool,
+      ?prevent_backdrop_close: bool,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Modal Header subcomponent.
+    def odt_modal_header: (
+      ?title: String?,
+      ?subtitle: String?,
+      ?dismissible: bool,
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Modal Body subcomponent.
+    def odt_modal_body: (
+      **untyped
+    ) ?{ () -> untyped } -> untyped
+
+    # Renders an ODT Modal Footer subcomponent.
+    def odt_modal_footer: (
+      **untyped
+    ) ?{ () -> untyped } -> untyped
   end
 end