[Documentation] Add close_button example + API Reference tables

- New 'Close Button' example box: clicking spawns a toast with X
  visible at top-right (top of stack inside item).
- Toaster JS spawn now honors detail.closeButton: appends a top-right
  ghost X button and adds pr-10 to the cloned node.
- API Reference section after About:
  - Toaster (Region) props: 12 entries with default + values + desc.
  - ToastItem props: 7 entries.
  - JS API options: 10 entries (callable as RubyUI.toast.* or via
    ruby-ui:toast CustomEvent detail).
- Reusable inline props_table helper; uses RubyUI Table primitives.

Author: djalmaaraujo

docs/app/javascript/controllers/ruby_ui/toaster_controller.js

@@ -121,6 +121,18 @@ export default class extends Controller {
       node.appendChild(btn)
     }
 
+    if (detail.closeButton) {
+      const x = document.createElement("button")
+      x.type = "button"
+      x.dataset.slot = "close"
+      x.dataset.action = "click->ruby-ui--toast#dismiss"
+      x.setAttribute("aria-label", "Close toast")
+      x.className = "absolute right-2 top-2 size-6 cursor-pointer rounded-md text-foreground/60 p-0 flex items-center justify-center transition-colors hover:bg-muted hover:text-foreground focus:outline-none focus:ring-1 focus:ring-ring"
+      x.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-3.5"><path d="M18 6 6 18"></path><path d="m6 6 12 12"></path></svg><span class="sr-only">Close</span>'
+      node.classList.add("pr-10")
+      node.appendChild(x)
+    }
+
     this._listEl.appendChild(node)
     return node.id
   }

docs/app/javascript/controllers/toast_demo_controller.js

@@ -8,6 +8,7 @@ const PRESETS = {
   error: { variant: "error", title: "Event has not been created" },
   with_action: { variant: "default", title: "Event has been created", action: { label: "Undo" } },
   text_only: { variant: "default", title: "Event has been created" },
+  close_button: { variant: "default", title: "Event has been created", description: "Close it manually with the X.", closeButton: true },
 }
 
 export default class extends Controller {
@@ -29,7 +30,11 @@ export default class extends Controller {
     }
 
     const preset = PRESETS[kind] || PRESETS.default
-    const opts = { description: preset.description, action: preset.action }
+    const opts = {
+      description: preset.description,
+      action: preset.action,
+      closeButton: preset.closeButton,
+    }
     const fn = t[preset.variant] || t
     fn(preset.title, opts)
   }

docs/app/views/docs/toast.rb

@@ -11,7 +11,8 @@ class Views::Docs::Toast < Views::Base
     {key: "error", label: "Error", title: "Event has not been created"},
     {key: "with_action", label: "With Action", title: "Event has been created", action_label: "Undo"},
     {key: "promise", label: "Promise", title: nil},
-    {key: "text_only", label: "Text Only", title: "Event has been created"}
+    {key: "text_only", label: "Text Only", title: "Event has been created"},
+    {key: "close_button", label: "Close Button", title: "Event has been created"}
   ].freeze
 
   POSITIONS = %w[top-left top-center top-right bottom-left bottom-center bottom-right].freeze
@@ -114,10 +115,93 @@ def view_template
         plain "."
       end
 
+      Heading(level: 2) { "API Reference" }
+
+      Heading(level: 3) { "Toaster (Region)" }
+      props_table(REGION_PROPS)
+
+      Heading(level: 3) { "ToastItem" }
+      props_table(ITEM_PROPS)
+
+      Heading(level: 3) { "JS API options" }
+      p(class: "text-muted-foreground text-sm") do
+        plain "Second argument to "
+        code(class: "rounded bg-muted px-1.5 py-0.5 text-xs") { "RubyUI.toast.<variant>(message, options)" }
+        plain " or "
+        code(class: "rounded bg-muted px-1.5 py-0.5 text-xs") { "ruby-ui:toast" }
+        plain " CustomEvent detail."
+      end
+      props_table(JS_OPTIONS)
+
       render Docs::ComponentsTable.new(component_files(component))
     end
   end
 
+  REGION_PROPS = [
+    {name: "position", default: ":bottom_right", values: ":top_left | :top_center | :top_right | :bottom_left | :bottom_center | :bottom_right", description: "Where the toaster mounts on the viewport."},
+    {name: "expand", default: "false", values: "Boolean", description: "Always show items expanded (no stack peek)."},
+    {name: "max", default: "3", values: "Integer", description: "Max visible toasts before oldest auto-evicts."},
+    {name: "duration", default: "4000", values: "Integer (ms)", description: "Default lifetime per toast. Pass 0 or Infinity to disable auto-dismiss."},
+    {name: "gap", default: "14", values: "Integer (px)", description: "Spacing between toasts when expanded."},
+    {name: "offset", default: "24", values: "Integer (px)", description: "Distance from the viewport edge."},
+    {name: "theme", default: ":system", values: ":system | :light | :dark", description: "Color scheme override."},
+    {name: "rich_colors", default: "false", values: "Boolean", description: "Enable variant-tinted backgrounds."},
+    {name: "close_button", default: "false", values: "Boolean", description: "Render an X button in every toast (top-right)."},
+    {name: "hotkey", default: '%w[alt t]', values: "Array<String>", description: "Keyboard shortcut to focus the first toast."},
+    {name: "dir", default: ":ltr", values: ":ltr | :rtl", description: "Text direction."},
+    {name: "flash", default: "nil", values: "Hash | nil", description: "Pass `helpers.flash.to_h` to render Rails flash on initial load."}
+  ].freeze
+
+  ITEM_PROPS = [
+    {name: "variant", default: ":default", values: ":default | :success | :error | :warning | :info | :loading", description: "Visual + a11y role + icon."},
+    {name: "id", default: "nil", values: "String", description: "DOM id; auto-generated when not provided."},
+    {name: "duration", default: "nil", values: "Integer | nil", description: "Override the Region default. nil inherits."},
+    {name: "dismissible", default: "true", values: "Boolean", description: "Allow Escape, swipe, X, and force-dismiss to close."},
+    {name: "invert", default: "false", values: "Boolean", description: "Invert background/foreground (light-on-dark in light theme)."},
+    {name: "on_dismiss", default: "nil", values: "String", description: "Stimulus action descriptor fired when the user dismisses."},
+    {name: "on_auto_close", default: "nil", values: "String", description: "Stimulus action descriptor fired when the timer expires."}
+  ].freeze
+
+  JS_OPTIONS = [
+    {name: "title", default: "—", values: "String", description: "Headline text. Falls back to the first positional argument."},
+    {name: "description", default: "—", values: "String", description: "Secondary line under the title."},
+    {name: "duration", default: "(Region default)", values: "Number | Infinity", description: "ms before auto-dismiss. Infinity = sticky."},
+    {name: "action", default: "—", values: "{ label, onClick }", description: "Primary action button rendered inside the toast."},
+    {name: "cancel", default: "—", values: "{ label, onClick }", description: "Secondary dismiss button."},
+    {name: "closeButton", default: "false", values: "Boolean", description: "Force an X close button on this toast."},
+    {name: "position", default: "(Region default)", values: "String", description: "Per-toast position override (changes Region's data-position before append)."},
+    {name: "id", default: "(auto)", values: "String", description: "Set a stable id (used by .dismiss(id) and .promise)."},
+    {name: "dismissible", default: "true", values: "Boolean", description: "Disable Escape / swipe / dismiss-all for this toast."},
+    {name: "className", default: "—", values: "String", description: "Extra classes appended to the rendered <li>."}
+  ].freeze
+
+  private
+
+  def props_table(rows)
+    div(class: "border rounded-lg overflow-hidden") do
+      Table do
+        TableHeader do
+          TableRow do
+            TableHead { "Prop" }
+            TableHead { "Default" }
+            TableHead { "Values" }
+            TableHead(class: "w-full") { "Description" }
+          end
+        end
+        TableBody do
+          rows.each do |r|
+            TableRow do
+              TableCell { InlineCode { r[:name] } }
+              TableCell { InlineCode { r[:default] } }
+              TableCell(class: "whitespace-normal") { InlineCode { r[:values] } }
+              TableCell(class: "text-muted-foreground") { r[:description] }
+            end
+          end
+        end
+      end
+    end
+  end
+
   private
 
   def example_box(ex)

gem/lib/ruby_ui/toast/toaster_controller.js

@@ -121,6 +121,18 @@ export default class extends Controller {
       node.appendChild(btn)
     }
 
+    if (detail.closeButton) {
+      const x = document.createElement("button")
+      x.type = "button"
+      x.dataset.slot = "close"
+      x.dataset.action = "click->ruby-ui--toast#dismiss"
+      x.setAttribute("aria-label", "Close toast")
+      x.className = "absolute right-2 top-2 size-6 cursor-pointer rounded-md text-foreground/60 p-0 flex items-center justify-center transition-colors hover:bg-muted hover:text-foreground focus:outline-none focus:ring-1 focus:ring-ring"
+      x.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-3.5"><path d="M18 6 6 18"></path><path d="m6 6 12 12"></path></svg><span class="sr-only">Close</span>'
+      node.classList.add("pr-10")
+      node.appendChild(x)
+    }
+
     this._listEl.appendChild(node)
     return node.id
   }