odt-ui-rails 2.2.0 → 2.2.1

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.1"
 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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: odt-ui-rails
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.2.1
 platform: ruby
 authors:
 - Pixel
@@ -29,7 +29,164 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
-description: Server-rendered Rails UI helpers and design tokens for ODT-Lightweight-UI.
+description: "<div align=\"center\">\n\n# ODT UI for Ruby on Rails (`odt-ui-rails`)\n\n**Standalone
+  CSS-first design tokens, Hotwire-ready UI components, and ActionView helpers for
+  Ruby on Rails.**\n\n[![Gem Version](https://badge.fury.io/rb/odt-ui-rails.svg)](https://badge.fury.io/rb/odt-ui-rails)\n[![License:
+  MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.0-ruby.svg)](https://www.ruby-lang.org)\n[![Rails](https://img.shields.io/badge/Rails-%3E%3D%206.1-red.svg)](https://rubyonrails.org)\n[![Hotwire
+  Ready](https://img.shields.io/badge/Hotwire-Turbo%20%26%20Stimulus-orange.svg)](https://hotwired.dev)\n[![Type
+  Checked](https://img.shields.io/badge/RBS-Type%20Signatures-green.svg)](sig/odt_ui.rbs)\n\n</div>\n\n---\n\n##
+  Overview\n\n`odt-ui-rails` brings the **ODT Design System** directly into Ruby on
+  Rails. It is architected from the ground up to provide a **Standalone CSS First**
+  experience:\n\n- \U0001F4E6 **Zero Host Build Tools Required:** Ships pre-compiled
+  CSS custom properties and `.odt-*` component styles. Works out-of-the-box with Propshaft,
+  Sprockets, or no asset pipeline at all.\n- ⚡ **Seamless Tailwind CSS v4 Interoperability:**
+  Includes a complete `@theme` token configuration for Tailwind v4 projects, allowing
+  custom utility classes (`class: \"...\"`) to merge effortlessly onto components.\n-
+  \U0001F680 **Hotwire & Turbo Native:** First-class helpers for Turbo Streams (`odt_toast_stream`),
+  Flash message auto-toasts (`odt_flash_toasts`), and Stimulus-powered Modals (`odt_modal`).\n-
+  \U0001F48E **Strict Type Signatures:** Full RBS definitions included for Ruby LSP,
+  Steep, and Solargraph IDE autocompletion.\n\n---\n\n## Table of Contents\n\n- [Installation](#installation)\n-
+  [Asset Pipeline Configuration](#asset-pipeline-configuration)\n- [Component Reference](#component-reference)\n
+  \ - [Feedback & Overlays](#feedback--overlays)\n    - [Toasts & Toaster](#toasts--toaster)\n
+  \   - [Modals](#modals)\n    - [Alerts](#alerts)\n  - [Actions & Indicators](#actions--indicators)\n
+  \   - [Buttons](#buttons)\n    - [Badges](#badges)\n  - [Form Controls](#form-controls)\n
+  \   - [Input Field](#input-field)\n    - [Textarea](#textarea)\n    - [Select Dropdown](#select-dropdown)\n
+  \   - [Checkbox & Radio](#checkbox--radio)\n    - [Form Group](#form-group)\n  -
+  [Layout & Typography](#layout--typography)\n    - [Cards](#cards)\n    - [Typography
+  (Heading & Text)](#typography-heading--text)\n    - [Avatars](#avatars)\n- [Theming
+  & Dark Mode](#theming--dark-mode)\n- [License](#license)\n\n---\n\n## Installation\n\nAdd
+  the gem to your application's `Gemfile`:\n\n```ruby\ngem \"odt-ui-rails\", \"~>
+  2.2.0\"\n```\n\nInstall dependencies:\n\n```bash\nbundle install\n```\n\nRun the
+  automated install generator:\n\n```bash\nbin/rails g odt:install\n```\n\nThe generator
+  will:\n\n1. Detect your asset pipeline (Tailwind CSS v4, Propshaft, or Sprockets)
+  and safely configure the required `@import` statements.\n2. Copy `sig/odt_ui.rbs`
+  for Ruby LSP IDE autocompletion.\n3. Copy Stimulus controllers (`odt_toast_controller.js`,
+  `odt_modal_controller.js`) to `app/javascript/controllers/` if Stimulus is present.\n\n---\n\n##
+  Asset Pipeline Configuration\n\nIf configuring stylesheets manually, use the configuration
+  below:\n\n### Option A: Tailwind CSS v4 (`app/assets/tailwind/application.css`)\n\n```css\n@import
+  \"tailwindcss\";\n@import \"odt_ui/tokens.css\";\n@import \"odt_ui/styles.css\";\n@import
+  \"odt_ui/theme.css\";\n```\n\n### Option B: Propshaft / Sprockets / Standard Rails
+  (`app/assets/stylesheets/application.css`)\n\n```css\n@import \"odt_ui/tokens.css\";\n@import
+  \"odt_ui/styles.css\";\n```\n\n---\n\n## Component Reference\n\nAll helpers are
+  globally available in all ERB templates, layouts, and helpers.\n\n---\n\n### Feedback
+  & Overlays\n\n#### Toasts & Toaster\n\nProvides viewport stacking containers, automated
+  Flash message toasts on redirects, and Turbo Stream responses for async form actions.\n\n```erb\n<%#
+  In app/views/layouts/application.html.erb %>\n<body class=\"bg-surface text-fg font-sans
+  antialiased\">\n  <%= odt_toaster position: :top_right do %>\n    <%= odt_flash_toasts
+  %>\n  <% end %>\n\n  <%= yield %>\n</body>\n```\n\n**Controller Turbo Stream Action:**\n\n```ruby\ndef
+  create\n  @todo = Todo.new(todo_params)\n  if @todo.save\n    respond_to do |format|\n
+  \     format.turbo_stream do\n        render turbo_stream: [\n          turbo_stream.prepend(\"todos\",
+  @todo),\n          odt_toast_stream(\"Todo created successfully!\", variant: :success)\n
+  \       ]\n      end\n      format.html { redirect_to todos_path, notice: \"Todo
+  created successfully!\" }\n    end\n  end\nend\n```\n\n**Individual Toast Helper:**\n\n```erb\n<%=
+  odt_toast \"Settings updated\", title: \"Saved\", variant: :success, duration: 4000
+  %>\n<%= odt_toast \"Failed to sync records\", variant: :danger %>\n```\n\n| Parameter
+  \    | Type      | Default    | Description                                                                  |\n|
+  :------------ | :-------- | :--------- | :---------------------------------------------------------------------------
+  |\n| `message`     | `String`  | `nil`      | Toast description or body text                                               |\n|
+  `title`       | `String`  | `nil`      | Optional bold header title                                                   |\n|
+  `variant`     | `Symbol`  | `:success` | `:success`, `:warning`, `:danger`, `:error`,
+  `:info`, `:loading`, `:frosted` |\n| `duration`    | `Integer` | `4000`     | Auto-dismiss
+  duration in ms (`0` to disable)                                 |\n| `dismissible`
+  | `Boolean` | `true`     | Renders close button (`×`)                                                   |\n\n---\n\n####
+  Modals\n\nAccessible dialog containers with backdrop overlay, ESC key handling,
+  scroll locking, and smooth scale transitions.\n\n```erb\n<%# Trigger Button %>\n<%=
+  odt_button \"New Task\", color: :primary, data: { action: \"click->odt-modal#open\"
+  } %>\n\n<%# Standard Modal %>\n<%= odt_modal id: \"new_task_modal\", title: \"Create
+  Task\", subtitle: \"Add a task to your board\", size: :md do %>\n  <%= render \"form\",
+  todo: Todo.new %>\n<% end %>\n\n<%# Custom Composition Modal %>\n<%= odt_modal id:
+  \"confirm_delete_modal\", size: :sm do %>\n  <%= odt_modal_header title: \"Delete
+  Item?\", subtitle: \"This action cannot be undone.\" %>\n  <%= odt_modal_body do
+  %>\n    <p class=\"text-sm text-fg-muted\">Are you sure you want to permanently
+  remove this record?</p>\n  <% end %>\n  <%= odt_modal_footer do %>\n    <%= odt_button
+  \"Cancel\", variant: :ghost, data: { action: \"click->odt-modal#close\" } %>\n    <%=
+  odt_button \"Delete\", color: :danger, data: { turbo_method: :delete } %>\n  <%
+  end %>\n<% end %>\n```\n\n| Parameter                | Type      | Default  | Description
+  \                                 |\n| :----------------------- | :-------- | :-------
+  | :------------------------------------------- |\n| `id`                     | `String`
+  \ | `nil`    | HTML identifier for Stimulus/Turbo targeting |\n| `title` / `subtitle`
+  \    | `String`  | `nil`    | Header titles                                |\n|
+  `size`                   | `Symbol`  | `:md`    | `:sm`, `:md`, `:lg`, `:xl`, `:full`
+  \         |\n| `radius`                 | `Symbol`  | `:\"2xl\"` | `:none` to `:\"4xl\"`,
+  `:full`                 |\n| `dismissible`            | `Boolean` | `true`   | Renders
+  close button                         |\n| `open`                   | `Boolean` |
+  `false`  | Initial visible state                        |\n| `prevent_backdrop_close`
+  | `Boolean` | `false`  | Disables closing on overlay click            |\n\n---\n\n####
+  Alerts\n\nInline banners for status notices, warning messages, and form callouts.\n\n```erb\n<%=
+  odt_alert \"Your subscription will renew on May 1st.\", variant: :info %>\n<%= odt_alert
+  \"Payment failed. Please update billing info.\", variant: :danger, icon: \"fa-solid
+  fa-triangle-exclamation\" %>\n```\n\n---\n\n### Actions & Indicators\n\n#### Buttons\n\nVersatile
+  action buttons supporting brand colors, frosted glass surfaces, loading states,
+  and icon decorations.\n\n```erb\n<%# Standard Brand Action %>\n<%= odt_button \"Save
+  Changes\", color: :primary, variant: :filled, radius: :full %>\n\n<%# Secondary
+  & Frosted Glass %>\n<%= odt_button \"Secondary\", variant: :subtle, color: :secondary
+  %>\n<%= odt_button \"Frosted Glass\", variant: :frosted, color: :primary %>\n\n<%#
+  Link as Button %>\n<%= odt_button \"View Project\", href: project_path(@project),
+  variant: :subtle %>\n\n<%# Loading & Icons %>\n<%= odt_button \"Add Task\", icon:
+  \"fa-solid fa-plus\", color: :primary %>\n<%= odt_button \"Saving...\", loading:
+  true %>\n<%= odt_button icon: \"fa-solid fa-trash\", icon_only: true, color: :danger,
+  variant: :ghost %>\n```\n\n| Option                | Type      | Default    | Description
+  \                                                                                                       |\n|
+  :-------------------- | :-------- | :--------- | :-----------------------------------------------------------------------------------------------------------------
+  |\n| `variant`             | `Symbol`  | `:filled`  | `:filled`, `:subtle`, `:ghost`,
+  `:outline`, `:capsule`, `:frosted`, `:light`                                       |\n|
+  `color`               | `Symbol`  | `:primary` | `:primary`, `:secondary`, `:surface`,
+  `:muted`, `:inverse`, `:success`, `:warning`, `:danger`, `:info`, `:neutral` |\n|
+  `size`                | `Symbol`  | `:md`      | `:xs`, `:sm`, `:md`, `:lg`, `:xl`
+  \                                                                                 |\n|
+  `radius`              | `Symbol`  | `:\"2xl\"`   | `:none`, `:xs`, `:sm`, `:md`,
+  `:lg`, `:xl`, `:\"2xl\"`, `:\"3xl\"`, `:\"4xl\"`, `:full`                                  |\n|
+  `icon` / `right_icon` | `String`  | `nil`      | FontAwesome class or inline SVG
+  string                                                                             |\n|
+  `icon_only`           | `Boolean` | `false`    | Square icon button formatting                                                                                      |\n|
+  `loading`             | `Boolean` | `false`    | Replaces icon with spinning loader
+  \                                                                                |\n|
+  `disabled`            | `Boolean` | `false`    | HTML disabled state                                                                                                |\n|
+  `full_width`          | `Boolean` | `false`    | Expands width to 100%                                                                                              |\n\n---\n\n####
+  Badges\n\nCompact status indicators with optional indicator dots and icons.\n\n```erb\n<%=
+  odt_badge \"Active\", variant: :subtle, color: :success, dot: true %>\n<%= odt_badge
+  \"High Priority\", variant: :filled, color: :danger, radius: :full %>\n<%= odt_badge
+  \"Calendar\", icon: \"fa-regular fa-calendar\", variant: :outlined %>\n```\n\n---\n\n###
+  Form Controls\n\nAccessible form components complete with labels, helper text, error
+  validations, icons, and input adornments.\n\n```erb\n<%= form_with model: @user,
+  class: \"space-y-4\" do |f| %>\n  <%# Text Input with Left Icon %>\n  <%= odt_input(\n
+  \   label: \"Email Address\",\n    name: \"user[email]\",\n    value: @user.email,\n
+  \   type: \"email\",\n    placeholder: \"you@example.com\",\n    left_icon: \"fa-solid
+  fa-envelope\",\n    error: @user.errors[:email].first,\n    required: true\n  )
+  %>\n\n  <%# Textarea %>\n  <%= odt_textarea(\n    label: \"Bio\",\n    name: \"user[bio]\",\n
+  \   value: @user.bio,\n    rows: 4,\n    helper: \"Brief summary for your profile\"\n
+  \ ) %>\n\n  <%# Select Dropdown %>\n  <%= odt_select(\n    label: \"Country\",\n
+  \   name: \"user[country]\",\n    options: [[\"Thailand\", \"TH\"], [\"United States\",
+  \"US\"], [\"Japan\", \"JP\"]],\n    selected: @user.country,\n    prompt: \"Select
+  country\"\n  ) %>\n\n  <%# Checkbox %>\n  <%= odt_checkbox(\n    label: \"Subscribe
+  to newsletter\",\n    description: \"Receive product updates once a week\",\n    name:
+  \"user[subscribed]\",\n    checked: true,\n    color: :primary\n  ) %>\n\n  <%#
+  Radio Group %>\n  <%= odt_radio label: \"Monthly Billing\", name: \"plan\", value:
+  \"monthly\", checked: true %>\n  <%= odt_radio label: \"Annual Billing (Save 20%)\",
+  name: \"plan\", value: \"annual\" %>\n\n  <%# Custom Slot Form Group %>\n  <%= odt_form_group
+  label: \"Custom Input\", helper: \"Unique value required\" do %>\n    <input type=\"text\"
+  class=\"odt-input odt-input--outlined odt-input--md\" name=\"custom\" />\n  <% end
+  %>\n<% end %>\n```\n\n---\n\n### Layout & Typography\n\n#### Cards\n\nVersatile
+  containers supporting header metadata, multiple surface styles, and hover transitions.\n\n```erb\n<%=
+  odt_card title: \"Analytics Overview\", subtitle: \"Monthly performance\", variant:
+  :elevated, radius: :\"3xl\" do %>\n  <p class=\"text-sm text-fg\">Dashboard charts
+  and statistics...</p>\n<% end %>\n\n<%= odt_card variant: :frosted, radius: :\"2xl\",
+  hoverable: true do %>\n  <span>Interactive frosted glass card</span>\n<% end %>\n```\n\n####
+  Typography (`odt_heading` & `odt_text`)\n\nStandardized typographic elements mapped
+  to the design system scale.\n\n```erb\n<%= odt_heading \"Task Dashboard\", as: :h1,
+  size: :\"4xl\", weight: :bold, color: :strong %>\n<%= odt_heading \"Section Title\",
+  as: :h3, size: :xl %>\n\n<%= odt_text \"Manage all project deliverables in one workspace.\",
+  size: :sm, color: :muted %>\n<%= odt_text \"A very long single-line description...\",
+  truncate: true %>\n```\n\n#### Avatars\n\nRenders image avatars or automatically
+  computes two-letter initials from full names.\n\n```erb\n<%# Generates initials
+  avatar \"JD\" %>\n<%= odt_avatar name: \"John Doe\", size: :lg, color: :secondary
+  %>\n\n<%# Image avatar with fallback %>\n<%= odt_avatar src: \"https://avatar.vercel.sh/pixel\",
+  size: :md %>\n```\n\n---\n\n## Theming & Dark Mode\n\nThe design system is fully
+  dark mode ready. Apply `data-theme=\"dark\"` or the `.dark` class to `<html>` or
+  any sub-container:\n\n```html\n<html data-theme=\"dark\" class=\"dark\">\n  ...\n</html>\n```\n\nAll
+  design tokens (backgrounds, surfaces, borders, text, and shadows) adapt automatically
+  without custom CSS.\n\n---\n\n## License\n\nThe gem is available as open source
+  under the terms of the [MIT License](LICENSE).\n"
 email:
 - pixxel.tk@gmail.com
 executables: []
@@ -41,7 +198,11 @@ files:
 - app/assets/stylesheets/odt_ui/styles.css
 - app/assets/stylesheets/odt_ui/theme.css
 - app/assets/stylesheets/odt_ui/tokens.css
+- app/javascript/controllers/odt_modal_controller.js
+- app/javascript/controllers/odt_toast_controller.js
 - lib/generators/odt/install_generator.rb
+- lib/generators/odt/templates/odt_modal_controller.js
+- lib/generators/odt/templates/odt_toast_controller.js
 - lib/odt-ui-rails.rb
 - lib/odt_ui/engine.rb
 - lib/odt_ui/helper.rb
@@ -50,7 +211,11 @@ files:
 homepage: https://github.com/PixxelTK/ODT-Lightweight-UI
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/PixxelTK/ODT-Lightweight-UI
+  source_code_uri: https://github.com/PixxelTK/ODT-Lightweight-UI/tree/main/integrations/rails
+  documentation_uri: https://github.com/PixxelTK/ODT-Lightweight-UI/blob/main/integrations/rails/README.md
+  changelog_uri: https://github.com/PixxelTK/ODT-Lightweight-UI/releases
 rdoc_options: []
 require_paths:
 - lib
@@ -67,5 +232,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Ruby on Rails integration and helpers for ODT-Lightweight-UI
+summary: Standalone CSS design tokens, Hotwire components, and ActionView helpers
+  for Ruby on Rails
 test_files: []