hotwire-astra-ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d6d9fe4802aac692c58a1dad36a6613cf42220f13636c01183dff8ab09c4d60
+  data.tar.gz: 2f45ead1f195c0dfa698fb34cc50e763b067243c0dcb17d04271933b8b26b8b9
+SHA512:
+  metadata.gz: 03beaf5ee10b1cc94703c64526eaad38ead87dc8349a6bff927908e624e75380da5b21e8296997de4fdb544d790ac549cad4101ac62b771a24872918a25bebdc
+  data.tar.gz: a56a0cd7cef6920f6e71779321a9897234285ce3f2b1672e846fadc2f30841544a01edec0f80cdf3fa3cd8d582a4d2af0ff7335e67b106ecf50c50fbce85d39c

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Fernand Arioja
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,360 @@
+# Hotwire Astra UI 🌌
+
+**Hotwire Astra UI** is a **production-ready, accessible modal system for Rails** built with **Hotwire (Turbo + Stimulus)** and **Importmap**.
+
+It enables **fully server-rendered modals** using Turbo Frames, with **zero client-side configuration** and **no JavaScript frameworks**.
+
+If you are building Rails 7+ applications and want predictable, scalable modal behavior without SPA complexity, Astra UI is designed for you.
+
+---
+
+## ✨ Features
+
+### 🔌 Zero-JavaScript Setup
+Designed for **Rails 7+**, **Hotwire**, and **Importmap**.
+Install the gem, run the generator, and start rendering modals immediately.
+
+No client state. No bundlers. No framework lock-in.
+
+---
+
+### 🪜 Recursive (Stacked) Modals
+Open modals **on top of modals** using nested Turbo Frames.
+
+Each modal layer:
+- is independently closable
+- maintains its own lifecycle
+- works with normal Rails controllers
+
+Infinite stacking, zero configuration.
+
+---
+
+### 🎞️ CSS-Driven Animations
+Entry and exit transitions are powered by **CSS variables**, not JavaScript.
+
+- Works with Tailwind or plain CSS
+- Respects `prefers-reduced-motion`
+- Fully overrideable
+
+---
+
+### 🔄 Automatic Close on Turbo Success
+Modals close automatically after successful Turbo form submissions.
+
+No callbacks. No client logic.
+Just follow the Turbo lifecycle.
+
+---
+
+### 🎨 Headless UI Design
+Astra UI ships with safe defaults, but **nothing is opinionated**.
+
+- Override everything with CSS variables
+- Compatible with design systems
+- No forced colors, spacing, or typography
+
+---
+
+### ♿ Accessibility-First
+- Proper dialog semantics
+- Keyboard navigation
+- Focus management
+- ESC and backdrop handling
+
+---
+
+## 📦 Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "hotwire-astra-ui", "0.1.0"
+```
+
+Install and run the generator:
+
+```bash
+bundle install
+bin/rails generate hotwire_astra_ui:install
+```
+
+The installer registers the Stimulus controller for you. If your app does not have `app/javascript/controllers/index.js`, add this registration manually:
+
+```js
+import HotwireAstraUiModalController from "hotwire_astra_ui/modal_controller"
+application.register("hotwire-astra-ui-modal", HotwireAstraUiModalController)
+```
+
+The installer adds a persistent Turbo Frame to your layout:
+
+```erb
+<%= turbo_frame_tag "astra_modal" %>
+```
+
+This frame is used to render modal content.
+
+## 📦 npm Package (JS + CSS)
+
+The JS-only shell is also published to npm:
+
+```bash
+npm install @digi-archive/hotwire-astra-ui
+```
+
+If you want to pin via Importmap (using the jspm CDN):
+
+```ruby
+# config/importmap.rb
+pin "@digi-archive/hotwire-astra-ui", to: "https://ga.jspm.io/npm:@digi-archive/hotwire-astra-ui@0.1.0/app/javascript/hotwire-astra-ui.js"
+```
+
+Register the controller:
+
+```js
+import HotwireAstraUiModalController from "@digi-archive/hotwire-astra-ui"
+application.register("hotwire-astra-ui-modal", HotwireAstraUiModalController)
+```
+
+Load the CSS from the same CDN:
+
+```erb
+<link rel="stylesheet" href="https://ga.jspm.io/npm:@digi-archive/hotwire-astra-ui@0.1.0/hotwire-astra-ui.css">
+```
+
+## 🧩 JS-Only (Importmap Pin)
+
+If you only want the **Stimulus controller** (and will provide your own HTML/CSS), you can pin the JS directly with Importmap from the gem:
+
+```ruby
+# config/importmap.rb
+pin "hotwire_astra_ui/modal_controller", to: ""
+```
+
+Register the controller:
+
+```js
+import HotwireAstraUiModalController from "hotwire_astra_ui/modal_controller"
+application.register("hotwire-astra-ui-modal", HotwireAstraUiModalController)
+```
+
+You must also provide:
+
+- The modal HTML structure with the correct `data-controller` and target attributes
+- The CSS (either copy `app/assets/stylesheets/hotwire/astra_ui/astra_ui.css` or reimplement it)
+
+Example HTML structure (JS-only):
+
+```erb
+<div data-controller="hotwire-astra-ui-modal"
+     data-hotwire-astra-ui-modal-target="backdrop"
+     data-action="click->hotwire-astra-ui-modal#backdropClick"
+     class="astra-modal-backdrop astra-default">
+
+  <div class="astra-modal-container astra-modal-size-md"
+       data-hotwire-astra-ui-modal-target="container"
+       data-action="click->hotwire-astra-ui-modal#stopPropagation"
+       role="dialog"
+       aria-modal="true"
+       aria-label="Example Dialog"
+       tabindex="-1">
+    <div class="astra-modal-header">
+      <h2>Example Dialog</h2>
+      <button type="button" data-action="hotwire-astra-ui-modal#close" class="astra-close-btn" aria-label="Close dialog">&times;</button>
+    </div>
+
+    <div class="astra-modal-body">
+      Your content goes here.
+    </div>
+  </div>
+</div>
+```
+
+### 📦 npm + Importmap (JS + CSS)
+
+If you publish the npm package `@digi-archive/hotwire-astra-ui`, you can pin it via Importmap using the jspm CDN:
+
+```ruby
+# config/importmap.rb
+pin "@digi-archive/hotwire-astra-ui", to: "https://ga.jspm.io/npm:@digi-archive/hotwire-astra-ui@0.1.0/app/javascript/hotwire-astra-ui.js"
+```
+
+Register the controller:
+
+```js
+import HotwireAstraUiModalController from "@digi-archive/hotwire-astra-ui"
+application.register("hotwire-astra-ui-modal", HotwireAstraUiModalController)
+```
+
+To load the CSS from npm, include the stylesheet from the same CDN:
+
+```erb
+<link rel="stylesheet" href="https://ga.jspm.io/npm:@digi-archive/hotwire-astra-ui@0.1.0/hotwire-astra-ui.css">
+```
+
+## 🎨 Styles
+
+Import the base stylesheet:
+
+```css
+/*
+ *= require hotwire_astra_ui/astra_ui
+ */
+```
+
+All visual customization is done via CSS variables.
+
+## 🚀 Basic Usage
+
+1. Trigger the Modal
+
+Target the modal Turbo Frame:
+
+```erb
+<%= link_to "New Post", new_post_path, data: { turbo_frame: "astra_modal" } %>
+```
+
+2. Render the Modal in a View Template
+```ruby
+<%= astra_modal(title: "Create a New Post") do %>
+  <%= render partial: "form" %>
+<% end %>
+```
+
+That’s it.
+No JavaScript. No client state.
+
+## 🧩 Advanced Usage
+
+### 🧰 Component Parameters
+
+`Hotwire::AstraUi::ModalComponent.new` accepts:
+
+- `title:` string or nil. If present, renders the header and provides `aria-labelledby`.
+- `id:` Turbo Frame id (default: `"astra_modal"`).
+- `theme_class:` CSS class applied to the backdrop (default: `"astra-default"`).
+- `aria_label:` used when `title` is nil (default: `"Dialog"`).
+- `size:` one of `:sm`, `:md`, `:lg`, `:xl` (default: `:md`).
+- `backdrop_close:` boolean for backdrop click to close (default: `true`).
+- `return_focus:` CSS selector to focus after close (default: `nil`).
+
+### 🪄 Convenience Helper
+
+Render from a view:
+
+```erb
+<%= astra_modal(title: "Create a New Post") do %>
+  <%= render partial: "form" %>
+<% end %>
+```
+
+### 🔁 Stacked (Nested) Modals
+
+Open a modal from inside another modal by targeting the next frame:
+
+```erb
+<%= link_to "Confirm Delete",
+            confirm_delete_path,
+            data: { turbo_frame: "astra_modal_next" } %>
+```
+
+Template:
+
+```erb
+<%= astra_modal(title: "Are you sure?", id: "astra_modal_next") do %>
+  This action cannot be undone.
+<% end %>
+```
+
+Each modal layer remains isolated and predictable.
+
+### 🔒 Close Modals from the Server (Turbo Streams)
+
+Close the modal directly from the server:
+
+```erb
+<%= close_astra_modal_tag %>
+```
+
+Close a specific frame by id:
+
+```erb
+<%= close_astra_modal_tag(id: "astra_modal_next") %>
+```
+
+Useful for:
+
+- form submissions
+- background jobs
+- multi-step workflows
+
+### 🧱 Size Variants
+
+Set a modal size with `size:`:
+
+```ruby
+render Hotwire::AstraUi::ModalComponent.new(title: "Large Modal", size: :lg)
+```
+
+Available sizes: `:sm`, `:md`, `:lg`, `:xl`.
+
+### 🧲 Backdrop Click & Focus Return
+
+Disable backdrop click to close:
+
+```ruby
+render Hotwire::AstraUi::ModalComponent.new(title: "Locked", backdrop_close: false)
+```
+
+Return focus to a specific element after close:
+
+```ruby
+render Hotwire::AstraUi::ModalComponent.new(title: "Edit", return_focus: "#edit-button")
+```
+
+## 🎨 Customization (CSS Variables)
+
+Override the look without touching gem code:
+
+```css
+:root {
+  --astra-modal-bg: #1e293b;
+  --astra-modal-radius: 0px;
+  --astra-backdrop-blur: 10px;
+  --astra-transition-duration: 500ms;
+}
+```
+
+Works with:
+
+- Tailwind CSS
+- Dark mode
+- Design tokens
+- Enterprise UI standards
+
+## 🧪 Development
+
+Run the dummy app locally:
+
+```bash
+cd test/dummy
+bin/rails s
+```
+
+## ✅ Testing
+
+Run the test suite:
+
+```bash
+bin/test
+```
+
+Or directly via Rake:
+
+```bash
+bundle exec rake test
+```
+
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/app/assets/stylesheets/hotwire/astra_ui/astra_ui.css

@@ -0,0 +1,104 @@
+/* Hotwire Astra UI - Core Styles
+  Customization: Override these variables in your application.css 
+*/
+:root {
+  /* Layout & Depth */
+  --astra-modal-z: 1000;
+  --astra-modal-max-width: 500px;
+  --astra-modal-radius: 0.75rem;
+  --astra-modal-bg: #ffffff;
+  --astra-backdrop-color: rgba(15, 23, 42, 0.6);
+  --astra-backdrop-blur: 4px;
+
+  /* Animation Timings */
+  --astra-transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
+  --astra-transition-duration: 300ms;
+}
+
+/* --- Backdrop --- */
+.astra-modal-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: var(--astra-modal-z);
+  background-color: var(--astra-backdrop-color);
+  backdrop-filter: blur(var(--astra-backdrop-blur));
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+  width: 100%;
+  
+  /* Initial state for animation */
+  opacity: 0;
+  transition: opacity var(--astra-transition-duration) var(--astra-transition-timing);
+}
+
+.astra-backdrop-enter-active {
+  opacity: 1;
+}
+
+.astra-modal-container {
+  width: 100%;
+  max-width: var(--astra-modal-max-width);
+  border-radius: var(--astra-modal-radius);
+  background: var(--astra-modal-bg);
+  box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
+  overflow: hidden;
+
+  /* Initial state for animation */
+  opacity: 0;
+  transform: translateY(20px) scale(0.95);
+  transition:
+    opacity var(--astra-transition-duration) var(--astra-transition-timing),
+    transform var(--astra-transition-duration) var(--astra-transition-timing);
+}
+
+.astra-modal-size-sm { --astra-modal-max-width: 360px; }
+.astra-modal-size-md { --astra-modal-max-width: 520px; }
+.astra-modal-size-lg { --astra-modal-max-width: 720px; }
+.astra-modal-size-xl { --astra-modal-max-width: 960px; }
+
+.astra-enter-active {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+}
+
+/* --- Content Areas --- */
+.astra-modal-header {
+  padding: 1.25rem;
+  border-bottom: 1px solid #e2e8f0;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.astra-modal-header h2 {
+  margin: 0;
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: #1e293b;
+}
+
+.astra-modal-body {
+  padding: 1.5rem;
+}
+
+.astra-close-btn {
+  cursor: pointer;
+  background: transparent;
+  border: none;
+  font-size: 1.5rem;
+  color: #94a3b8;
+  line-height: 1;
+}
+
+.astra-close-btn:hover {
+  color: #475569;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .astra-modal-backdrop,
+  .astra-modal-container {
+    transition: none;
+  }
+}

data/app/components/hotwire/astra_ui/modal_component.html.erb

@@ -0,0 +1,31 @@
+<%= helpers.turbo_frame_tag @id, data: { turbo_action: "none" } do %>
+  <div data-controller="hotwire-astra-ui-modal"
+       data-hotwire-astra-ui-modal-backdrop-close-value="<%= backdrop_close_value %>"
+       <%= return_focus.present? ? "data-hotwire-astra-ui-modal-return-focus-value=\"#{return_focus}\"" : "" %>
+       data-hotwire-astra-ui-modal-target="backdrop"
+       data-action="click->hotwire-astra-ui-modal#backdropClick"
+       class="astra-modal-backdrop <%= @theme_class %>">
+    
+    <div class="astra-modal-container <%= size_class %>"
+         data-hotwire-astra-ui-modal-target="container"
+         data-action="click->hotwire-astra-ui-modal#stopPropagation"
+         role="dialog"
+         aria-modal="true"
+         <%= @title.present? ? "aria-labelledby=\"#{title_id}\"" : "aria-label=\"#{aria_label}\"" %>
+         tabindex="-1">
+      <div class="astra-modal-header">
+        <% if @title.present? %>
+          <h2 id="<%= title_id %>"><%= @title %></h2>
+        <% end %>
+        <button type="button" data-action="hotwire-astra-ui-modal#close" class="astra-close-btn" aria-label="Close dialog">&times;</button>
+      </div>
+      
+      <div class="astra-modal-body">
+        <%= content %>
+
+        <%# This is the "landing zone" for a potential second modal %>
+        <%= helpers.turbo_frame_tag next_modal_id %>
+      </div>
+    </div>
+  </div>
+<% end %>

data/app/components/hotwire/astra_ui/modal_component.rb

@@ -0,0 +1,48 @@
+module Hotwire::AstraUi
+  class ModalComponent < ViewComponent::Base
+    def initialize(
+      title: nil,
+      id: nil,
+      theme_class: "astra-default",
+      aria_label: "Dialog",
+      size: :md,
+      backdrop_close: true,
+      return_focus: nil
+    )
+      @title = title
+      # Default to the base 'astra_modal' if no specific ID is provided
+      @id = id || "astra_modal"
+      @theme_class = theme_class
+      @aria_label = aria_label
+      @size = size
+      @backdrop_close = backdrop_close
+      @return_focus = return_focus
+    end
+
+    def next_modal_id
+      "#{@id}_next"
+    end
+
+    def title_id
+      "#{@id}_title"
+    end
+
+    def aria_label
+      @aria_label
+    end
+
+    def size_class
+      return nil if @size.nil?
+
+      "astra-modal-size-#{@size}"
+    end
+
+    def backdrop_close_value
+      @backdrop_close ? "true" : "false"
+    end
+
+    def return_focus
+      @return_focus
+    end
+  end
+end

data/app/helpers/hotwire/astra_ui/modal_helper.rb

@@ -0,0 +1,19 @@
+module Hotwire
+  module AstraUi
+    module ModalHelper
+      def astra_modal_frame_tag
+        turbo_frame_tag "astra_modal"
+      end
+
+      def astra_modal(title:, **options, &block)
+        render Hotwire::AstraUi::ModalComponent.new(title: title, **options) do
+          capture(&block)
+        end
+      end
+
+      def close_astra_modal_tag(id: "astra_modal")
+        turbo_stream.replace id, html: ""
+      end
+    end
+  end
+end

data/app/javascript/hotwire-astra-ui.js

@@ -0,0 +1,68 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["container", "backdrop", "body"]
+  static values = {
+    title: String,
+    size: { type: String, default: "md" },
+    backdropClose: { type: Boolean, default: true }
+  }
+
+  connect() {
+    this.buildModal()
+    this.animateIn()
+    document.body.style.overflow = "hidden"
+  }
+
+  disconnect() {
+    document.body.style.overflow = "auto"
+  }
+
+  buildModal() {
+    const originalContent = this.element.innerHTML
+
+    this.element.innerHTML = `
+      <div class="astra-modal-backdrop" data-astra-ui-shell-target="backdrop" data-action="click->astra-ui-shell#backdropClick">
+        <div class="astra-modal-container astra-modal-size-${this.sizeValue}" data-astra-ui-shell-target="container" data-action="click->astra-ui-shell#stopPropagation">
+          <div class="astra-header">
+            <h3>${this.titleValue || ""}</h3>
+            <button type="button" data-action="astra-ui-shell#close" style="cursor:pointer;border:none;background:none;font-size:1.5rem;">&times;</button>
+          </div>
+          <div class="astra-body" data-astra-ui-shell-target="body">
+            ${originalContent}
+          </div>
+        </div>
+      </div>
+    `
+  }
+
+  animateIn() {
+    requestAnimationFrame(() => {
+      this.backdropTarget.classList.add("astra-enter-active")
+      this.containerTarget.classList.add("astra-enter-active")
+    })
+  }
+
+  backdropClick(e) {
+    if (!this.backdropCloseValue) return
+    if (e.target === this.backdropTarget) this.close()
+  }
+
+  stopPropagation(e) {
+    e.stopPropagation()
+  }
+
+  async close() {
+    this.backdropTarget.classList.remove("astra-enter-active")
+    this.containerTarget.classList.remove("astra-enter-active")
+    await new Promise(res => setTimeout(res, 300))
+
+    const frame = this.element.closest("turbo-frame")
+    if (frame) {
+      frame.src = null
+      frame.innerHTML = ""
+    } else {
+      this.element.innerHTML = ""
+    }
+  }
+}

data/app/javascript/hotwire_astra_ui/modal_controller.js

@@ -0,0 +1,163 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["container", "backdrop"]
+  static values = {
+    backdropClose: { type: Boolean, default: true },
+    returnFocus: String
+  }
+
+  connect() {
+    this.previouslyFocused = document.activeElement
+    this.handleKeydown = this.handleKeydown.bind(this)
+    document.addEventListener("keydown", this.handleKeydown)
+
+    this.adjustZIndex()
+    this.animateIn()
+    this.lockScroll()
+    this.focusFirst()
+  }
+
+  disconnect() {
+    document.removeEventListener("keydown", this.handleKeydown)
+    this.restoreFocus()
+  }
+
+  adjustZIndex() {
+    // Check how many modals are currently open
+    const openModals = this.openModals().length
+    if (openModals > 1) {
+      // Offset the Z-index so the new one is on top
+      const baseZ = parseInt(getComputedStyle(document.documentElement).getPropertyValue('--astra-modal-z')) || 1000
+      this.element.style.zIndex = baseZ + (openModals * 10)
+    }
+  }
+
+  lockScroll() {
+    if (this.openModals().length === 1) {
+      document.body.style.overflow = "hidden"
+    }
+  }
+
+  animateIn() {
+    this.backdropTarget.classList.add("astra-backdrop-enter")
+
+    requestAnimationFrame(() => {
+      this.containerTarget.classList.add("astra-enter-active")
+      this.backdropTarget.classList.add("astra-backdrop-enter-active")
+    })
+  }
+
+  async close(e = null) {
+    if (e) e.preventDefault()
+    if (!this.isTopmost()) return
+    
+    this.containerTarget.classList.remove("astra-enter-active")
+    this.backdropTarget.classList.remove("astra-backdrop-enter-active")
+
+    await new Promise(res => setTimeout(res, this.transitionDurationMs()))
+
+    // Important: Only clear the specific frame this modal lives in
+    const frame = this.element.closest("turbo-frame")
+    frame.src = null
+    frame.innerHTML = ""
+    
+    // Only restore scrolling if this was the last modal
+    if (this.openModals().length === 0) {
+      document.body.style.overflow = "auto"
+    }
+  }
+
+  backdropClick(e) {
+    if (!this.backdropCloseValue) return
+    if (e.target === this.backdropTarget) {
+      this.close(e)
+    }
+  }
+
+  stopPropagation(e) {
+    e.stopPropagation()
+  }
+
+  handleKeydown(e) {
+    if (!this.isTopmost()) return
+
+    if (e.key === "Escape") {
+      e.preventDefault()
+      this.close()
+      return
+    }
+
+    if (e.key === "Tab") {
+      this.trapFocus(e)
+    }
+  }
+
+  isTopmost() {
+    const modals = this.openModals()
+    return modals.length > 0 && modals[modals.length - 1] === this.backdropTarget
+  }
+
+  openModals() {
+    return Array.from(document.querySelectorAll('.astra-modal-backdrop'))
+  }
+
+  focusableElements() {
+    return Array.from(
+      this.containerTarget.querySelectorAll(
+        'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])'
+      )
+    )
+  }
+
+  focusFirst() {
+    const focusables = this.focusableElements()
+    if (focusables.length > 0) {
+      focusables[0].focus()
+    } else {
+      this.containerTarget.focus()
+    }
+  }
+
+  trapFocus(e) {
+    const focusables = this.focusableElements()
+    if (focusables.length === 0) {
+      e.preventDefault()
+      this.containerTarget.focus()
+      return
+    }
+
+    const first = focusables[0]
+    const last = focusables[focusables.length - 1]
+
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault()
+      last.focus()
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault()
+      first.focus()
+    }
+  }
+
+  restoreFocus() {
+    if (this.hasReturnFocusValue) {
+      const target = document.querySelector(this.returnFocusValue)
+      if (target && target.focus) {
+        target.focus()
+        return
+      }
+    }
+
+    if (this.previouslyFocused && this.previouslyFocused.focus) {
+      this.previouslyFocused.focus()
+    }
+  }
+
+  transitionDurationMs() {
+    const raw = getComputedStyle(document.documentElement).getPropertyValue('--astra-transition-duration').trim()
+    if (raw.endsWith("ms")) return parseFloat(raw)
+    if (raw.endsWith("s")) return parseFloat(raw) * 1000
+    const parsed = parseFloat(raw)
+    return Number.isNaN(parsed) ? 300 : parsed
+  }
+}

data/config/importmap.rb

@@ -0,0 +1,3 @@
+pin "hotwire_astra_ui/modal_controller", to: "hotwire_astra_ui/modal_controller.js"
+# Back-compat alias
+pin "hotwire_astra_ui_modal", to: "hotwire_astra_ui/modal_controller.js"

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/generators/hotwire_astra_ui/install_generator.rb

@@ -0,0 +1,60 @@
+module HotwireAstraUi
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Configures the application for Hotwire Astra UI"
+
+      def add_turbo_frame_to_layout
+        layout_file = "app/views/layouts/application.html.erb"
+
+        if File.exist?(layout_file)
+          # Check if it's already there to avoid duplicates
+          if File.read(layout_file).include?('turbo_frame_tag "astra_modal"')
+            say_status("skipped", "turbo_frame_tag already exists in application.html.erb", :yellow)
+          else
+            # Insert before the closing body tag
+            insert_into_file layout_file, "\n    <%= turbo_frame_tag \"astra_modal\" %>", before: /^  <\/body>/
+            say_status("inserted", "turbo_frame_tag into application.html.erb", :green)
+          end
+        else
+          say_status("error", "application.html.erb not found. Please add <%= turbo_frame_tag 'astra_modal' %> manually.", :red)
+        end
+      end
+
+      def create_initializer
+        initializer "hotwire_astra_ui.rb" do
+          <<~RUBY
+            # Configuration for Hotwire Astra UI
+            # You can add global theme settings here later
+          RUBY
+        end
+      end
+
+      def register_stimulus_controller
+        controllers_index = "app/javascript/controllers/index.js"
+        import_line = 'import HotwireAstraUiModalController from "hotwire_astra_ui/modal_controller"'
+        register_line = 'application.register("hotwire-astra-ui-modal", HotwireAstraUiModalController)'
+
+        if File.exist?(controllers_index)
+          file_contents = File.read(controllers_index)
+
+          if file_contents.include?(import_line) || file_contents.include?(register_line)
+            say_status("skipped", "Stimulus controller already registered in controllers/index.js", :yellow)
+          else
+            append_to_file controllers_index, "\n#{import_line}\n#{register_line}\n"
+            say_status("inserted", "Registered Hotwire Astra UI Stimulus controller", :green)
+          end
+        else
+          say_status("warning", "controllers/index.js not found. Please register the controller manually.", :yellow)
+        end
+      end
+
+      def show_post_install_message
+        say "\n🚀 Hotwire Astra UI is installed!", :magenta
+        say "1. Use data-turbo-frame='astra_modal' on your links."
+        say "2. Render the component: render Hotwire::AstraUi::ModalComponent.new(title: 'Hello')"
+      end
+    end
+  end
+end

data/lib/hotwire/astra_ui/engine.rb

@@ -0,0 +1,15 @@
+module Hotwire
+  module AstraUi
+    class Engine < ::Rails::Engine
+      # This hook allows the host app to see the engine's assets
+      initializer "hotwire_astra_ui.assets" do |app|
+        app.config.assets.paths << root.join("app/javascript")
+      end
+
+      # This automatically pins the engine's JS in the host's importmap
+      initializer "hotwire_astra_ui.importmap", before: "importmap" do |app|
+        (app.config.importmap.paths ||= []) << root.join("config/importmap.rb")
+      end
+    end
+  end
+end

data/lib/hotwire/astra_ui/ui.rb

@@ -0,0 +1,12 @@
+require "importmap-rails"
+require "view_component"
+require "hotwire/astra_ui/version"
+require "hotwire/astra_ui/engine"
+
+module Hotwire
+  module AstraUi
+    # Namespace module for the gem. Loading this file wires up the engine
+    # and version, which is enough for the host app to mount assets and
+    # importmap pins.
+  end
+end

data/lib/hotwire/astra_ui/version.rb

@@ -0,0 +1,5 @@
+module Hotwire
+  module AstraUi
+    VERSION = "0.1.0"
+  end
+end

data/lib/tasks/hotwire/astra/ui_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :hotwire_astra_ui do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: hotwire-astra-ui
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fernand
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.2
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: stimulus-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Hotwire Astra UI provides production-ready, accessible modal dialogs
+  for Rails apps using Turbo Frames and Stimulus. Importmap-friendly, server-rendered,
+  and framework-free, with stacked modals, CSS-driven animations, and full customization
+  via CSS variables.
+email:
+- dev.cloud.asm@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/hotwire/astra_ui/astra_ui.css
+- app/components/hotwire/astra_ui/modal_component.html.erb
+- app/components/hotwire/astra_ui/modal_component.rb
+- app/helpers/hotwire/astra_ui/modal_helper.rb
+- app/javascript/hotwire-astra-ui.js
+- app/javascript/hotwire_astra_ui/modal_controller.js
+- config/importmap.rb
+- config/routes.rb
+- lib/generators/hotwire_astra_ui/install_generator.rb
+- lib/hotwire/astra_ui/engine.rb
+- lib/hotwire/astra_ui/ui.rb
+- lib/hotwire/astra_ui/version.rb
+- lib/tasks/hotwire/astra/ui_tasks.rake
+homepage: https://www.digi-archive.com/articles/hotwire-astra-ui
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org/
+  homepage_uri: https://www.digi-archive.com/articles/hotwire-astra-ui
+  source_code_uri: https://github.com/wwwfernand/hotwire-astra-ui
+  changelog_uri: https://github.com/wwwfernand/hotwire-astra-ui/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Accessible Hotwire modal component for Rails (Turbo + Stimulus) with Importmap
+  support
+test_files: []