rails_modal_manager 1.0.59 → 1.0.61

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65777a92905a2ad64ca23a3d2a571c52c9cea95ac6797eb56eba7a567651053e
-  data.tar.gz: 418078c26f467088fa6dcac03042c67458a0238722648ba79ecbe5b8ec297520
+  metadata.gz: '09dbfd6b3213ab34ae1874fa5e785061ae3e896415949b76fc54d8504df04420'
+  data.tar.gz: f64b4b8b42503cbea4dcdfcf7bf439353456f055863803af2628e39b71859b91
 SHA512:
-  metadata.gz: a3ae6da5585652a3229d2c876cc3cc667a86f4169e8abf949ec80408d5e8cb198d4d6cef83bbff4c89f311f19700a55bc8a69ca8d0f449f31d49116925e3db70
-  data.tar.gz: b225ccbff9262aaa54d130f0190d7a945dd5cb43206dcea1992cf34d74d6b26f73011c7b78032501bbcfa607996a7d3f1494cb4cda046b7e80bb7fa73b3fa9f9
+  metadata.gz: de7b11bb9f2ea74aa9afb1c61dec4069e544ec98132aefc9e19f513b9baa26d246cb43d4f7de214ee9646eb6e27e81e76c176721bee0a2e0e765d0668980c8fd
+  data.tar.gz: 62a26a444c72824cc5964d14004bdf879505b983bd2016a769d2d53c5998b05107ec17ef4974a28e80f32f29b139024e8338411ce737cb673f8661debe9fa224

data/README.md

@@ -12,6 +12,13 @@ Rails 애플리케이션을 위한 고급 모달 매니저입니다.
 > - **헤더 색상** — 본문의 `#3b82f6` 파란색 → v1.0.57 부터 `#3e6187` 블루 차콜
 > - **푸터 버튼** — `onclick` 은 v1.0.55 에서 deprecated. `type: "submit"` + `form:` 패턴 사용
 > - **z-index** — v1.0.58 에서 계층 재배치 (overlay 1400 < modal 1500~8000 < taskbar 9000 < confirm 10000)
+>
+> ⚠️ **이벤트 이름 (2026-08-07 교정)** — 아래 본문과 구 OPTIONS.md 에 `rmm:closed` / `rmm:minimize` /
+> `rmm:maximize` 로 적혀 있던 것은 **오기입니다. 그 이름으로는 발화되지 않습니다.**
+> 실제 이름은 `rmm-modal:closed` / `rmm-modal:minimize` / `rmm-modal:maximize` 이며
+> (Stimulus `this.dispatch()` 가 컨트롤러 identifier `rmm-modal` 을 접두어로 붙임),
+> `rmm:open` · `rmm:close` 만 `index.js` 가 직접 dispatch 해 접두어가 없습니다.
+> 정확한 목록·권장 패턴은 **[OPTIONS.md → Events](OPTIONS.md#events)** 참조.
 
 ---
 
@@ -646,6 +653,9 @@ const descendants = modalStore.getAllDescendants('parent-modal')
   --rmm-bg: #ffffff;
   --rmm-border: #e2e8f0;
   --rmm-overlay-bg: rgba(0, 0, 0, 0.5);
+  /* v1.0.60 — 오버레이 닫기 어포던스. 끄려면 closable 을 default 로 덮으면 된다 */
+  --rmm-overlay-cursor: default;          /* 오버레이로는 닫을 수 없음 */
+  --rmm-overlay-cursor-closable: pointer; /* 클릭 또는 더블클릭으로 닫힘 */
 
   /* Header */
   --rmm-header-height: 48px;

data/app/assets/stylesheets/rails_modal_manager.css

@@ -39,6 +39,10 @@
   /* Overlay */
   --rmm-overlay-bg: rgba(0, 0, 0, 0.5);
   --rmm-overlay-blur: 0px;
+  /* v1.0.60 — 오버레이 닫기 가능 여부를 커서로 알린다.
+     끄려면 프로젝트에서 --rmm-overlay-cursor-closable: default; 로 덮으면 된다. */
+  --rmm-overlay-cursor: default;          /* 오버레이로는 닫을 수 없음 */
+  --rmm-overlay-cursor-closable: pointer; /* 클릭 또는 더블클릭으로 닫힘 */
 
   /* Header — v1.0.57 블루 차콜 (사용자 지정 팔레트) */
   --rmm-header-bg: #3e6187;
@@ -228,6 +232,29 @@
               visibility var(--rmm-animation-duration) var(--rmm-animation-timing);
   backdrop-filter: blur(1px);
   -webkit-backdrop-filter: blur(1px);
+  /* v1.0.60 — 기본은 "닫을 수 없음". 닫히는 경우만 아래 속성 선택자가 덮는다. */
+  cursor: var(--rmm-overlay-cursor);
+}
+
+/* ⭐v1.0.60 — 오버레이 닫기 어포던스
+   오버레이 클릭으로 닫히는지 여부는 지금까지 화면에 아무 단서가 없어서, 사용자는 눌러 보기 전까지
+   알 수 없었다(닫히지 않으면 "고장난 것"으로 읽힌다). 정책은 이미 오버레이 요소의 data 속성에
+   실려 있으므로, 그 값을 그대로 커서로 표현한다.
+
+   ⚠ 색상이 아니라 커서를 쓰는 이유:
+     · 모달 중첩 시 오버레이가 여러 장 겹치는데, 색은 섞여서 판별이 안 되지만 커서는 항상 최상단 것만 보인다
+     · 색만으로 정보를 전달하면 색각 이상 사용자가 구분할 수 없다 (WCAG 1.4.1)
+     · 학습이 필요 없다 — pointer 는 웹의 보편 규약이다
+
+   ⚠ 선언 순서 주의: dblclick 규칙이 반드시 뒤에 와야 한다.
+     rmm_overlay_controller#handleClick 은 `if (!closeOnClick || closeOnDblclick) return` 이라
+     더블클릭 모드에서는 close_on_click 값과 무관하게 단일 클릭이 무시된다. 반대로 handleDblclick 은
+     closeOnDblclick 만 확인하므로, close_on_click=false + dblclick=true 조합도 "닫을 수 있는" 상태다. */
+.rmm-overlay[data-rmm-overlay-close-on-click-value="true"] {
+  cursor: var(--rmm-overlay-cursor-closable);
+}
+.rmm-overlay[data-rmm-overlay-close-on-dblclick-value="true"] {
+  cursor: var(--rmm-overlay-cursor-closable);
 }
 
 .rmm-overlay.rmm-active {
@@ -2391,3 +2418,36 @@
     visibility: hidden !important;
   }
 }
+
+
+/* ============================================
+   v1.0.61 — Shell (placeholder) modal
+   openModalShell() 로 띄운 틀과, 틀을 제자리 교체할 때의 «애니메이션 없이 즉시» 표시
+   ============================================ */
+.rmm-modal.rmm-instant,
+.rmm-overlay.rmm-instant {
+  transition: none !important;
+}
+
+.rmm-shell-skeleton {
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.rmm-shell-line {
+  height: 14px;
+  border-radius: 6px;
+  background: linear-gradient(90deg, #eef2f6 25%, #f8fafc 37%, #eef2f6 63%);
+  background-size: 400% 100%;
+  animation: rmm-shell-shimmer 1.4s ease infinite;
+}
+.rmm-shell-line-sm { width: 35%; }
+.rmm-shell-line-md { width: 60%; }
+.rmm-shell-line-lg { width: 90%; }
+
+@keyframes rmm-shell-shimmer {
+  0% { background-position: 100% 50%; }
+  100% { background-position: 0 50%; }
+}

data/app/helpers/rails_modal_manager/modal_helper.rb

@@ -42,6 +42,38 @@ module RailsModalManager
       )
     end
 
+    # Render the shell (placeholder) modal template — v1.0.61+
+    # Render once in the layout. openModalShell() clones it to show a modal frame immediately
+    # while the real modal is fetched; replaceModalShell() swaps it in place (same history entry).
+    # The block is the loading body (skeleton); a built-in skeleton is used when omitted.
+    #
+    # @example In layout
+    #   <%= rmm_modal_shell_template %>
+    #   <%= rmm_modal_shell_template { render "shared/modal_skeleton" } %>
+    #
+    def rmm_modal_shell_template(options = {}, &block)
+      content = block_given? ? capture(&block) : rmm_default_shell_skeleton
+      modal = render(
+        partial: "rails_modal_manager/modal",
+        locals: {
+          title: "__RMM_SHELL_TITLE__",
+          size: "md",
+          draggable: false,
+          resizable: false,
+          minimizable: false,
+          close_on_overlay: true,
+          enable_history_stack: true
+        }.merge(options).merge(modal_id: "__RMM_SHELL__", block_content: content)
+      )
+      content_tag(:template, modal, id: "rmm-modal-shell-template")
+    end
+
+    def rmm_default_shell_skeleton
+      content_tag(:div, class: "rmm-shell-skeleton", "aria-hidden": "true") do
+        safe_join(%w[lg md lg sm md lg].map { |w| content_tag(:div, "", class: "rmm-shell-line rmm-shell-line-#{w}") })
+      end
+    end
+
     # Render the global taskbar component
     # Should be included once in the layout, typically at the end of body
     #

data/app/javascript/rails_modal_manager/controllers/rmm_modal_controller.js

@@ -148,8 +148,17 @@ export default class extends Controller {
       return // Already open
     }
 
+    // v1.0.61+: 자리표시(shell) 모달 인계 — replaceModalShell() 이 data-rmm-adopt-shell 로 지정.
+    // 틀이 이미 차지한 브라우저 history 칸과 포커스 복귀 대상을 넘겨받고, 틀은 애니메이션 없이 걷어낸다.
+    const adoptShellId = this.element.dataset.rmmAdoptShell
+    let shell = null
+    if (adoptShellId) {
+      delete this.element.dataset.rmmAdoptShell
+      shell = this._takeOverShell(adoptShellId, modalId)
+    }
+
     // Save previous focus
-    this.previousFocus = document.activeElement
+    this.previousFocus = shell ? shell.previousFocus : document.activeElement
 
     // Check for saved size (use persistentId or modalId)
     let initialSize = this.sizeValue
@@ -196,8 +205,9 @@ export default class extends Controller {
       historyStackManager.addHisData('modal', modalId, () => this.close('history'))
     }
 
-    // Show modal with animation
-    this.showModal()
+    // Show modal with animation (틀 인계 시에는 제자리 교체 — 열림 애니메이션 없이 즉시)
+    this.showModal({ instant: !!shell })
+    if (shell) shell.remove()
 
     // Add event listeners
     this.addEventListeners()
@@ -372,7 +382,7 @@ export default class extends Controller {
   // Animation
   // ============================================
 
-  showModal() {
+  showModal({ instant = false } = {}) {
     const modal = this.element
     const overlay = this.getOverlay()
 
@@ -382,8 +392,7 @@ export default class extends Controller {
     // Apply depth class for visual hierarchy (parent/child/grandchild)
     this.applyDepthClass()
 
-    // Start animation
-    requestAnimationFrame(() => {
+    const activate = () => {
       modal.classList.add('rmm-active')
       if (overlay) overlay.classList.add('rmm-active')
 
@@ -391,7 +400,54 @@ export default class extends Controller {
       if (this.focusTrapValue) {
         this.setupFocusTrap()
       }
-    })
+    }
+
+    if (instant) {
+      // v1.0.61+: 틀(shell) 교체 — 같은 태스크 안에서 틀 제거와 함께 반영돼 중간 프레임이 그려지지 않는다
+      modal.classList.add('rmm-instant')
+      if (overlay) overlay.classList.add('rmm-instant')
+      activate()
+      requestAnimationFrame(() => requestAnimationFrame(() => {
+        modal.classList.remove('rmm-instant')
+        if (overlay) overlay.classList.remove('rmm-instant')
+      }))
+      return
+    }
+
+    // Start animation
+    requestAnimationFrame(activate)
+  }
+
+  /**
+   * v1.0.61+: 자리표시(shell) 모달의 자리를 넘겨받는다.
+   * - history: 틀이 push 한 칸을 그대로 두고 id·닫기 함수만 이 모달로 이관(replaceHisData)
+   * - store: 틀을 조용히 제거(z-index 는 이 모달이 이어서 받는다)
+   * 틀이 이미 닫혔으면(뒤로가기·ESC 등) null — 호출 측(replaceModalShell)이 먼저 걸러낸다.
+   * @returns {{ previousFocus: Element|null, remove: Function }|null}
+   */
+  _takeOverShell(shellId, modalId) {
+    if (!modalStore.getModalConfig(shellId)) return null
+    const shellEl = document.getElementById(shellId)
+    const shellCtrl = shellEl && this.application.getControllerForElementAndIdentifier(shellEl, 'rmm-modal')
+    const previousFocus = shellCtrl ? shellCtrl.previousFocus : null
+
+    if (this.enableHistoryStackValue) {
+      historyStackManager.replaceHisData('modal', shellId, modalId, () => this.close('history'))
+    } else {
+      // 이 모달은 history 를 쓰지 않는다 — 틀의 칸은 일반 닫기처럼 되돌린다
+      historyStackManager.removeHisData('modal', shellId)
+    }
+    modalStore.unregisterCloseCallback(shellId)
+    modalStore.closeModal(shellId)
+
+    return {
+      previousFocus,
+      remove: () => {
+        const overlayEl = document.getElementById(`${shellId}-overlay`)
+        if (overlayEl) overlayEl.remove()
+        if (shellEl) shellEl.remove()
+      }
+    }
   }
 
   /**

data/app/javascript/rails_modal_manager/history_stack_manager.js

@@ -199,6 +199,33 @@ function silentRemoveHisData(type, id) {
   return true;
 }
 
+/**
+ * Hand an existing history entry over to another target without touching browser history (v1.0.61+).
+ * Used when a placeholder («shell») modal is swapped for the real modal: the pushState made when the
+ * shell opened stays as-is, only the entry's id and close function move to the real modal, so the
+ * back button closes the real modal and no orphan history state is left behind.
+ * @param {string} type - Target type ('modal', ...)
+ * @param {string} oldId - Current owner id
+ * @param {string} newId - New owner id
+ * @param {Function} close - New close function (optional)
+ * @returns {boolean} Whether the entry was found and handed over
+ */
+function replaceHisData(type, oldId, newId, close) {
+  if (typeof window === 'undefined') return false;
+  if (!isEnabledForDevice(type)) return false;
+
+  const hisData = loadHisData();
+  const item = hisData.find((entry) => entry.type === type && entry.id === oldId);
+  if (!item) return false;
+
+  if (item.closeKey) closeFunctions.delete(item.closeKey);
+  item.id = newId;
+  item.closeKey = generateUUID();
+  if (close) closeFunctions.set(item.closeKey, close);
+  saveHisData(hisData);
+  return true;
+}
+
 /**
  * Remove multiple items from history stack at once
  * - Remove all specified items from stack
@@ -392,6 +419,7 @@ const historyStackManager = {
   removeHisData,
   removeMultipleHisData,
   silentRemoveHisData,
+  replaceHisData,
   popHisData,
   moveToTop,
 

data/app/javascript/rails_modal_manager/index.js

@@ -8,7 +8,7 @@
  * @license MIT
  */
 
-export const VERSION = "1.0.34"
+export const VERSION = "1.0.61"
 
 // Import core modules for internal use
 import modalStore, { MODAL_CONSTANTS, SIZE_CONFIG, POSITION_CONFIG, CASCADE_OFFSET, modalSizeStorage, modalUtils } from "rails_modal_manager/modal_store"
@@ -192,6 +192,134 @@ export function closeModal(modalId, source = 'programmatic') {
   }
 }
 
+// ============================================
+// Shell (placeholder) modal — v1.0.61+
+// ============================================
+// 서버 응답을 기다리는 동안 «모달 틀»을 먼저 띄우고, 실제 모달이 오면 그 자리를 제자리 교체한다.
+// 틀 마크업은 레이아웃에 한 번 렌더한 rmm_modal_shell_template(<template>)을 복제한다 — gem 의
+// 모달 파셜 그대로이므로 헤더·오버레이·크기 규칙이 실제 모달과 같다.
+
+const SHELL_TEMPLATE_ID = 'rmm-modal-shell-template'
+const SHELL_ID_TOKEN = '__RMM_SHELL__'
+const SHELL_TITLE_TOKEN = '__RMM_SHELL_TITLE__'
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))
+}
+
+/**
+ * Whether shell modals are available (the layout rendered rmm_modal_shell_template)
+ * @returns {boolean}
+ */
+export function modalShellAvailable() {
+  return !!document.getElementById(SHELL_TEMPLATE_ID)
+}
+
+/**
+ * Open a placeholder («shell») modal immediately while the real modal is being fetched.
+ * Pass the same size/height/persistentId as the real modal so the swap does not jump.
+ * @param {string} shellId - Unique id for the shell (e.g. `${modalId}-shell`)
+ * @param {Object} options
+ * @param {string} options.title - Header title while loading
+ * @param {string} options.size - 'fit'|'xss'|'xs'|'sm'|'md'|'lg'|'xl'|'full'
+ * @param {string} options.height - e.g. '90vh'
+ * @param {string} options.persistentId - Same persistent_id as the real modal (saved size is shared)
+ * @param {boolean} options.mobileDefaultMaximized
+ * @param {boolean} options.closeOnOverlay
+ * @returns {string|null} shellId, or null when the template is missing (caller falls back)
+ */
+export function openModalShell(shellId, options = {}) {
+  const template = document.getElementById(SHELL_TEMPLATE_ID)
+  if (!template || !shellId) return null
+  // 같은 id 의 틀이 아직 열려 있으면(같은 대상 재클릭) 그대로 쓴다. 닫히는 중·잔재면 즉시 걷어낸다 —
+  // 닫힘 애니메이션을 기다리는 사이 새 틀을 같은 id 로 넣으면 옛 틀의 정리가 새 틀을 지울 수 있다.
+  if (isModalShellOpen(shellId)) return shellId
+  removeShellDom(shellId)
+
+  const html = template.innerHTML
+    .split(SHELL_ID_TOKEN).join(shellId)
+    .split(SHELL_TITLE_TOKEN).join(escapeHtml(options.title || ''))
+  const temp = document.createElement('div')
+  temp.innerHTML = html
+  const modal = temp.querySelector(`#${CSS.escape(shellId)}`)
+  if (!modal) return null
+
+  const set = (name, value) => { if (value !== undefined && value !== null) modal.setAttribute(`data-rmm-modal-${name}-value`, String(value)) }
+  set('size', options.size)
+  set('height', options.height)
+  set('persistent-id', options.persistentId)
+  set('mobile-default-maximized', options.mobileDefaultMaximized)
+  set('close-on-overlay', options.closeOnOverlay)
+  const overlay = temp.querySelector(`#${CSS.escape(shellId)}-overlay`)
+  if (overlay && options.closeOnOverlay !== undefined) {
+    overlay.setAttribute('data-rmm-overlay-close-on-click-value', String(options.closeOnOverlay))
+  }
+  // connect() 가 openValue=true 를 보고 곧바로 연다
+  modal.setAttribute('data-rmm-modal-open-value', 'true')
+  modal.classList.add('rmm-shell')
+
+  const container = document.getElementById('child-modals-container') || document.body
+  while (temp.firstChild) container.appendChild(temp.firstChild)
+  return shellId
+}
+
+/**
+ * Whether the shell is still open (not closed by back button / ESC / overlay while loading)
+ * @param {string} shellId
+ * @returns {boolean}
+ */
+export function isModalShellOpen(shellId) {
+  return !!modalStore.getModalConfig(shellId)
+}
+
+/**
+ * Swap the shell for the real modal in place. The real modal must already be in the DOM (closed).
+ * The real modal inherits the shell's history entry, focus-return target and stacking slot, and
+ * appears without the opening animation.
+ * @param {string} shellId
+ * @param {string} modalId - The real modal's id
+ * @returns {boolean} false when the shell was already closed — the caller should discard the real modal
+ */
+export function replaceModalShell(shellId, modalId) {
+  const modalElement = document.getElementById(modalId)
+  if (!modalElement) return false
+  if (!isModalShellOpen(shellId)) {
+    discardModalShell(shellId)
+    return false
+  }
+  modalElement.dataset.rmmAdoptShell = shellId
+  openModal(modalId)
+  return true
+}
+
+/**
+ * Close (if open) and remove a shell — e.g. when fetching the real modal failed.
+ * @param {string} shellId
+ */
+function removeShellDom(shellId) {
+  const overlay = document.getElementById(`${shellId}-overlay`)
+  const shell = document.getElementById(shellId)
+  if (overlay) overlay.remove()
+  if (shell) shell.remove()
+}
+
+export function discardModalShell(shellId) {
+  const shell = document.getElementById(shellId)
+  if (!shell) return
+  // 정리 대상은 지금 시점의 요소로 고정(나중에 같은 id 로 들어온 새 틀을 건드리지 않게)
+  const overlay = document.getElementById(`${shellId}-overlay`)
+  const removeDom = () => {
+    if (overlay && overlay.parentNode) overlay.remove()
+    if (shell.parentNode) shell.remove()
+  }
+  if (isModalShellOpen(shellId)) {
+    shell.addEventListener('rmm-modal:closed', removeDom, { once: true })
+    closeModal(shellId)
+  } else {
+    removeDom()
+  }
+}
+
 /**
  * Close the topmost modal
  * @returns {string|null} The closed modal's ID or null if no modal was open

data/lib/rails_modal_manager/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsModalManager
-  VERSION = "1.0.59"
+  VERSION = "1.0.61"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_modal_manager
 version: !ruby/object:Gem::Version
-  version: 1.0.59
+  version: 1.0.61
 platform: ruby
 authors:
 - reshacs