admin-lte 4.0.4 → 4.2.0

package/src/ts/push-menu.ts

@@ -6,6 +6,7 @@
  * ----------------------------------------------------------------------------
  */
 
+import { BaseComponent, dispatchCustomEvent } from './base-component'
 import {
   getLifecycleSignal,
   onDOMContentLoaded
@@ -17,11 +18,17 @@ import {
  * ----------------------------------------------------------------------------
  */
 
-const DATA_KEY = 'lte.push-menu'
-const EVENT_KEY = `.${DATA_KEY}`
+const NAME = 'push-menu'
+const EVENT_KEY = `.lte.${NAME}`
+
+// Cancelable "before" events: preventDefault() aborts the state change.
 const EVENT_OPEN = `open${EVENT_KEY}`
 const EVENT_COLLAPSE = `collapse${EVENT_KEY}`
 
+// "After" events, dispatched once the classes have been applied.
+const EVENT_OPENED = `opened${EVENT_KEY}`
+const EVENT_COLLAPSED = `collapsed${EVENT_KEY}`
+
 const CLASS_NAME_SIDEBAR_MINI = 'sidebar-mini'
 const CLASS_NAME_SIDEBAR_EXPAND = 'sidebar-expand'
 const CLASS_NAME_SIDEBAR_OVERLAY = 'sidebar-overlay'
@@ -68,12 +75,44 @@ const Defaults: Config = {
  * ----------------------------------------------------------------------------
  */
 
-class PushMenu {
-  _element: HTMLElement
+class PushMenu extends BaseComponent {
+  static get NAME(): string {
+    return NAME
+  }
+
+  /**
+   * Look up the PushMenu already attached to the given element.
+   *
+   * @param element The sidebar element to look up.
+   * @returns The existing instance, or null if the sidebar has none yet.
+   */
+  static getInstance(element: Element | null | undefined): PushMenu | null {
+    return this._getInstance(element) as PushMenu | null
+  }
+
+  /**
+   * Look up the PushMenu attached to the given element, creating one when the
+   * element has none. `config` is ignored if an instance already exists.
+   *
+   * @param element The sidebar element.
+   * @param config Overrides merged over the defaults for a new instance.
+   * @returns The existing or newly created instance.
+   */
+  static getOrCreateInstance(element: HTMLElement, config: Partial<Config> = {}): PushMenu {
+    return this.getInstance(element) ?? new this(element, config)
+  }
+
+  /**
+   * The defaults merged with the overrides this instance was created with.
+   */
   _config: Config
 
-  constructor(element: HTMLElement, config: Config) {
-    this._element = element
+  /**
+   * @param element The sidebar element to attach to.
+   * @param config Overrides merged over the defaults.
+   */
+  constructor(element: HTMLElement, config: Partial<Config> = {}) {
+    super(element)
     this._config = { ...Defaults, ...config }
   }
 
@@ -118,6 +157,12 @@ class PushMenu {
    * Expand the sidebar menu.
    */
   expand(): void {
+    // The "open" event is cancelable: preventDefault() keeps the sidebar
+    // in its current state.
+    if (dispatchCustomEvent(this._element, EVENT_OPEN, { cancelable: true }).defaultPrevented) {
+      return
+    }
+
     // Remove the sidebar-collapse class. Only on mobile, add the sidebar-open
     // class to indicate the sidebar is explicitly open.
 
@@ -127,24 +172,26 @@ class PushMenu {
       document.body.classList.add(CLASS_NAME_SIDEBAR_OPEN)
     }
 
-    // Dispatch the expand event.
-
-    this._element.dispatchEvent(new Event(EVENT_OPEN))
+    dispatchCustomEvent(this._element, EVENT_OPENED)
   }
 
   /**
    * Collapse the sidebar menu.
    */
   collapse(): void {
+    // The "collapse" event is cancelable: preventDefault() keeps the sidebar
+    // in its current state.
+    if (dispatchCustomEvent(this._element, EVENT_COLLAPSE, { cancelable: true }).defaultPrevented) {
+      return
+    }
+
     // Remove the sidebar-open class (if present), and add the sidebar-collapse
     // class.
 
     document.body.classList.remove(CLASS_NAME_SIDEBAR_OPEN)
     document.body.classList.add(CLASS_NAME_SIDEBAR_COLLAPSE)
 
-    // Dispatch the collapse event.
-
-    this._element.dispatchEvent(new Event(EVENT_COLLAPSE))
+    dispatchCustomEvent(this._element, EVENT_COLLAPSED)
   }
 
   /**
@@ -317,12 +364,12 @@ class PushMenu {
 
     // When persistence is enabled and screen size is above the breakpoint, load
     // the saved sidebar state from local storage. Otherwise, use responsive
-    // logic to set the initial state. On low screen sizes, the sidebar should
-    // always be collapsed by default unless explicitly opened.
+    // logic to set the initial state (unless explicitly set as collapsed at
+    // initialization).
 
     if (this._config.enablePersistence && !this.isMobileSize()) {
       this.loadSidebarState()
-    } else {
+    } else if (!this.isCollapsed()) {
       this.updateStateByResponsiveLogic()
     }
   }
@@ -332,12 +379,40 @@ class PushMenu {
  * ----------------------------------------------------------------------------
  * Data Api implementation
  * ----------------------------------------------------------------------------
+ * Toggle clicks are handled by one delegated listener on `document`, so
+ * toggle buttons added later work and the listener survives Turbo's <body>
+ * swaps. The instance itself is created per page load below and can be
+ * retrieved anywhere with:
+ *
+ *   PushMenu.getInstance(document.querySelector('.app-sidebar'))
  */
 
+document.addEventListener('click', event => {
+  const target = event.target
+
+  if (!(target instanceof Element)) {
+    return
+  }
+
+  const button = target.closest(SELECTOR_SIDEBAR_TOGGLE)
+
+  if (!button) {
+    return
+  }
+
+  event.preventDefault()
+
+  const sidebar = document.querySelector(SELECTOR_APP_SIDEBAR) as HTMLElement | null
+
+  if (sidebar) {
+    PushMenu.getOrCreateInstance(sidebar).toggle()
+  }
+})
+
 onDOMContentLoaded(() => {
   // Find the sidebar element in the DOM.
 
-  const sidebar = document?.querySelector(SELECTOR_APP_SIDEBAR) as HTMLElement | undefined
+  const sidebar = document.querySelector(SELECTOR_APP_SIDEBAR) as HTMLElement | null
 
   if (!sidebar) {
     return
@@ -358,9 +433,11 @@ onDOMContentLoaded(() => {
       enablePersistenceAttr === 'true'
   }
 
-  // Initialize the PushMenu plugin (a unique instance).
+  // Initialize the PushMenu plugin (a unique instance per sidebar element;
+  // Turbo navigations swap in a fresh element, so a fresh instance is
+  // created and the old one is garbage-collected with the old <body>).
 
-  const pushMenu = new PushMenu(sidebar, config)
+  const pushMenu = PushMenu.getOrCreateInstance(sidebar, config)
   pushMenu.init()
 
   // Update the sidebar state only when the viewport crosses the sidebar
@@ -392,16 +469,23 @@ onDOMContentLoaded(() => {
   // Handle touch events on overlay (area outside sidebar), usually we want to
   // close the sidebar when the user taps outside the sidebar on mobile
   // devices.
+  //
+  // These are bound with the lifecycle signal even though the overlay lives
+  // inside <body>: the node above is reused when it already exists, so under a
+  // framework that re-initialises against a persistent <body>, an unsignalled
+  // binding would stack another set of handlers on the same element per cycle.
+
+  const overlaySignal = getLifecycleSignal()
 
   let overlayTouchMoved = false
 
   sidebarOverlay.addEventListener('touchstart', () => {
     overlayTouchMoved = false
-  }, { passive: true })
+  }, { passive: true, signal: overlaySignal })
 
   sidebarOverlay.addEventListener('touchmove', () => {
     overlayTouchMoved = true
-  }, { passive: true })
+  }, { passive: true, signal: overlaySignal })
 
   sidebarOverlay.addEventListener('touchend', event => {
     if (!overlayTouchMoved) {
@@ -410,33 +494,12 @@ onDOMContentLoaded(() => {
     }
 
     overlayTouchMoved = false
-  }, { passive: false })
+  }, { passive: false, signal: overlaySignal })
 
   sidebarOverlay.addEventListener('click', event => {
     event.preventDefault()
     pushMenu.collapse()
-  })
-
-  // Handle click events on sidebar toggle buttons.
-
-  const fullBtn = document.querySelectorAll(SELECTOR_SIDEBAR_TOGGLE)
-
-  fullBtn.forEach(btn => {
-    btn.addEventListener('click', event => {
-      event.preventDefault()
-
-      let button = event.currentTarget as HTMLElement | undefined
-
-      if (button?.dataset.lteToggle !== 'sidebar') {
-        button = button?.closest(SELECTOR_SIDEBAR_TOGGLE) as HTMLElement | undefined
-      }
-
-      if (button) {
-        event?.preventDefault()
-        pushMenu.toggle()
-      }
-    })
-  })
+  }, { signal: overlaySignal })
 })
 
 export default PushMenu

package/src/ts/treeview.ts

@@ -6,6 +6,7 @@
  * --------------------------------------------
  */
 
+import { BaseComponent, dispatchCustomEvent } from './base-component'
 import {
   onDOMContentLoaded,
   slideDown,
@@ -18,10 +19,14 @@ import {
  * ------------------------------------------------------------------------
  */
 
-// const NAME = 'Treeview'
-const DATA_KEY = 'lte.treeview'
-const EVENT_KEY = `.${DATA_KEY}`
+const NAME = 'treeview'
+const EVENT_KEY = `.lte.${NAME}`
 
+// Cancelable "before" events (dispatched on the nav-item as an action starts)
+const EVENT_EXPAND = `expand${EVENT_KEY}`
+const EVENT_COLLAPSE = `collapse${EVENT_KEY}`
+
+// "After" events (dispatched on the nav-item when the animation finished)
 const EVENT_EXPANDED = `expanded${EVENT_KEY}`
 const EVENT_COLLAPSED = `collapsed${EVENT_KEY}`
 const EVENT_LOAD_DATA_API = `load${EVENT_KEY}`
@@ -56,17 +61,30 @@ const setAriaExpanded = (navItem: Element, expanded: boolean): void => {
  * ====================================================
  */
 
-class Treeview {
-  _element: HTMLElement
+class Treeview extends BaseComponent {
+  static get NAME(): string {
+    return NAME
+  }
+
+  static getInstance(element: Element | null | undefined): Treeview | null {
+    return this._getInstance(element) as Treeview | null
+  }
+
+  static getOrCreateInstance(element: HTMLElement, config: Partial<Config> = {}): Treeview {
+    return this.getInstance(element) ?? new this(element, config)
+  }
+
   _config: Config
 
-  constructor(element: HTMLElement, config: Config) {
-    this._element = element
+  constructor(element: HTMLElement, config: Partial<Config> = {}) {
+    super(element)
     this._config = { ...Default, ...config }
   }
 
   open(): void {
-    const event = new Event(EVENT_EXPANDED)
+    if (dispatchCustomEvent(this._element, EVENT_EXPAND, { cancelable: true }).defaultPrevented) {
+      return
+    }
 
     if (this._config.accordion) {
       const openMenuList = this._element.parentElement?.querySelectorAll(`${SELECTOR_NAV_ITEM}.${CLASS_NAME_MENU_OPEN}`)
@@ -90,26 +108,36 @@ class Treeview {
     this._element.classList.add(CLASS_NAME_MENU_OPEN)
     setAriaExpanded(this._element, true)
 
-    const childElement = this._element?.querySelector(SELECTOR_TREEVIEW_MENU) as HTMLElement | undefined
+    const childElement = this._element.querySelector(SELECTOR_TREEVIEW_MENU) as HTMLElement | undefined
     if (childElement) {
       slideDown(childElement, this._config.animationSpeed)
     }
 
-    this._element.dispatchEvent(event)
+    setTimeout(() => {
+      if (this._element.classList.contains(CLASS_NAME_MENU_OPEN)) {
+        dispatchCustomEvent(this._element, EVENT_EXPANDED)
+      }
+    }, this._config.animationSpeed)
   }
 
   close(): void {
-    const event = new Event(EVENT_COLLAPSED)
+    if (dispatchCustomEvent(this._element, EVENT_COLLAPSE, { cancelable: true }).defaultPrevented) {
+      return
+    }
 
     this._element.classList.remove(CLASS_NAME_MENU_OPEN)
     setAriaExpanded(this._element, false)
 
-    const childElement = this._element?.querySelector(SELECTOR_TREEVIEW_MENU) as HTMLElement | undefined
+    const childElement = this._element.querySelector(SELECTOR_TREEVIEW_MENU) as HTMLElement | undefined
     if (childElement) {
       slideUp(childElement, this._config.animationSpeed)
     }
 
-    this._element.dispatchEvent(event)
+    setTimeout(() => {
+      if (!this._element.classList.contains(CLASS_NAME_MENU_OPEN)) {
+        dispatchCustomEvent(this._element, EVENT_COLLAPSED)
+      }
+    }, this._config.animationSpeed)
   }
 
   toggle(): void {
@@ -125,8 +153,50 @@ class Treeview {
  * ------------------------------------------------------------------------
  * Data Api implementation
  * ------------------------------------------------------------------------
+ * Clicks are handled by one delegated listener on `document`, so nav items
+ * added after load (dynamic menus, Turbo Frames) work without
+ * re-initialisation. Initial state (pre-opened menus, ARIA stamping) is
+ * applied per page load below.
  */
 
+document.addEventListener('click', event => {
+  const target = event.target
+
+  if (!(target instanceof Element)) {
+    return
+  }
+
+  const toggleRoot = target.closest(SELECTOR_DATA_TOGGLE) as HTMLElement | null
+
+  if (!toggleRoot) {
+    return
+  }
+
+  const targetItem = target.closest(SELECTOR_NAV_ITEM) as HTMLElement | null
+  const targetLink = target.closest(SELECTOR_NAV_LINK)
+
+  // Avoid creating Treeview instances on non menu elements
+  if (!targetItem?.querySelector(SELECTOR_TREEVIEW_MENU)) {
+    return
+  }
+
+  if (target.getAttribute('href') === '#' || targetLink?.getAttribute('href') === '#') {
+    event.preventDefault()
+  }
+
+  // Read config from data attributes on the treeview root, falling back to
+  // Default. The config of the first interaction sticks to the instance.
+  const accordionAttr = toggleRoot.dataset.accordion
+  const animationSpeedAttr = toggleRoot.dataset.animationSpeed
+
+  const config: Config = {
+    accordion: accordionAttr === undefined ? Default.accordion : accordionAttr === 'true',
+    animationSpeed: animationSpeedAttr === undefined ? Default.animationSpeed : Number(animationSpeedAttr)
+  }
+
+  Treeview.getOrCreateInstance(targetItem, config).toggle()
+})
+
 onDOMContentLoaded(() => {
   const openMenuItems = document.querySelectorAll(`${SELECTOR_NAV_ITEM}.${CLASS_NAME_MENU_OPEN}`)
 
@@ -149,42 +219,6 @@ onDOMContentLoaded(() => {
       }
     })
   })
-
-  const button = document.querySelectorAll(SELECTOR_DATA_TOGGLE)
-
-  button.forEach(btn => {
-    btn.addEventListener('click', event => {
-      const target = event.target as HTMLElement
-      const targetItem = target.closest(SELECTOR_NAV_ITEM) as HTMLElement | undefined
-      const targetLink = target.closest(SELECTOR_NAV_LINK) as HTMLAnchorElement | undefined
-      const targetTreeviewMenu = targetItem?.querySelector(SELECTOR_TREEVIEW_MENU) as HTMLElement | undefined
-      const lteToggleElement = event.currentTarget as HTMLElement
-
-      // Avoid creating Treeview instances on non menu elements
-      if (!targetTreeviewMenu) {
-        return
-      }
-
-      if (target?.getAttribute('href') === '#' || targetLink?.getAttribute('href') === '#') {
-        event.preventDefault()
-      }
-
-      if (targetItem) {
-        // Read data attributes
-        const accordionAttr = lteToggleElement.dataset.accordion
-        const animationSpeedAttr = lteToggleElement.dataset.animationSpeed
-
-        // Build config from data attributes, fallback to Default
-        const config: Config = {
-          accordion: accordionAttr === undefined ? Default.accordion : accordionAttr === 'true',
-          animationSpeed: animationSpeedAttr === undefined ? Default.animationSpeed : Number(animationSpeedAttr)
-        }
-
-        const data = new Treeview(targetItem, config)
-        data.toggle()
-      }
-    })
-  })
 })
 
-export default Treeview
+export default Treeview

package/src/ts/util/index.ts

@@ -16,6 +16,18 @@
  * cycle's listeners before the callbacks run again. Listeners bound to elements
  * inside <body> don't need the signal — Turbo discards the old <body>, so they
  * are cleaned up automatically.
+ *
+ * Turbo is not the only environment that renders after `DOMContentLoaded`:
+ * client-side frameworks that build the layout themselves (GWT, and other
+ * imperative widget toolkits) have an empty <body> when the initial batch runs,
+ * so the per-page init pass finds no sidebar and no menu. Those consumers call
+ * the exported `initialize()` once the layout is attached — it performs the same
+ * reset-then-replay cycle Turbo gets, without faking Turbo events.
+ *
+ * Unlike Turbo, such frameworks keep the same <body> across a re-init, so
+ * element-level listeners are NOT discarded for them. Callbacks should therefore
+ * pass `getLifecycleSignal()` to every `addEventListener` they make — including
+ * ones on elements — whenever the element can outlive the cycle.
  */
 
 const lifecycleCallbacks: Array<() => void> = []
@@ -24,7 +36,10 @@ const lifecycleCallbacks: Array<() => void> = []
 // without reassigning top-level bindings.
 const lifecycleState = {
   controller: new AbortController(),
-  hasInitialized: false
+  hasInitialized: false,
+  // True while the callback batch is executing — lets initialize() refuse
+  // re-entrant calls made from inside a lifecycle callback.
+  isReplaying: false
 }
 
 /**
@@ -40,9 +55,14 @@ const runLifecycleCallbacks = (): void => {
   }
 
   lifecycleState.hasInitialized = true
+  lifecycleState.isReplaying = true
 
-  for (const callback of lifecycleCallbacks) {
-    callback()
+  try {
+    for (const callback of lifecycleCallbacks) {
+      callback()
+    }
+  } finally {
+    lifecycleState.isReplaying = false
   }
 }
 
@@ -58,24 +78,66 @@ const onDOMContentLoaded = (callback: () => void): void => {
   }
 }
 
-// Initial page load.
+/**
+ * End the current lifecycle: abort the cycle's signal so listeners registered
+ * with it are removed, then arm a fresh cycle for the next replay.
+ *
+ * Exported for SPA containers that unmount the AdminLTE layout: calling it
+ * drops the window/document listeners the current cycle added without
+ * immediately re-initialising. Internally it is also the first half of
+ * `initialize()` and the `turbo:before-render` handler.
+ */
+const teardown = (): void => {
+  lifecycleState.controller.abort()
+  lifecycleState.controller = new AbortController()
+  lifecycleState.hasInitialized = false
+}
+
+/**
+ * Re-run every plugin's initialisation against the DOM as it stands right now.
+ *
+ * Intended for frameworks that render the layout after `DOMContentLoaded` has
+ * already fired — call it once the sidebar and menu are attached, and PushMenu,
+ * Treeview and ColorMode pick them up as if they had been in the initial HTML.
+ * Delegated click handling never needs this; only the per-page init pass does.
+ *
+ * The previous cycle is torn down first, so calling it repeatedly does not stack
+ * listeners registered with `getLifecycleSignal()`. Calling it before the
+ * initial batch has run (while `document.readyState === 'loading'`) runs that
+ * batch early, against whatever DOM exists at the time — the initial
+ * `DOMContentLoaded` pass below still replays against the complete DOM.
+ */
+const initialize = (): void => {
+  // Re-entrancy guard: a lifecycle callback calling initialize() would tear
+  // down its own cycle mid-replay and recurse without end.
+  if (lifecycleState.isReplaying) {
+    return
+  }
+
+  teardown()
+  runLifecycleCallbacks()
+}
+
+// Initial page load. Routed through initialize() so that an early initialize()
+// call (a framework initialising before the document finished loading) cannot
+// mark the cycle as done and suppress this pass — the replay tears the early
+// cycle down and re-runs every callback against the complete DOM.
 if (document.readyState === 'loading') {
-  document.addEventListener('DOMContentLoaded', runLifecycleCallbacks, { once: true })
+  document.addEventListener('DOMContentLoaded', initialize, { once: true })
 } else {
   runLifecycleCallbacks()
 }
 
 // Hotwired Turbo: drop the previous cycle's window/document listeners, then
-// re-run initialisation against the freshly rendered <body>.
-document.addEventListener('turbo:before-render', () => {
-  lifecycleState.controller.abort()
-  lifecycleState.controller = new AbortController()
-  lifecycleState.hasInitialized = false
-})
+// re-run initialisation against the freshly rendered <body>. The teardown has to
+// happen at `before-render` rather than as part of the replay, so the outgoing
+// <body>'s listeners are gone before Turbo swaps in the new one — which is why
+// this is the two-step form of `initialize()` rather than a call to it.
+document.addEventListener('turbo:before-render', teardown)
 
 document.addEventListener('turbo:load', runLifecycleCallbacks)
 
-/* ES2022 UTILITY FUNCTIONS */
+// ES2022 UTILITY FUNCTIONS
 
 /**
  * Check if an element has a specific data attribute using ES2022 Object.hasOwn()
@@ -109,7 +171,7 @@ const safePropertyAccess = (obj: Record<string, unknown>, property: string): unk
  * the previous animation's steps: without this, rapidly toggling a treeview or
  * card leaves a stale cleanup timer that strips height/transition mid-animation
  * and desyncs the element's display state from its component's classes. */
-const slideTimers = new WeakMap<HTMLElement, number[]>()
+const slideTimers = new WeakMap<HTMLElement, Array<ReturnType<typeof globalThis.setTimeout>>>()
 
 const cancelSlide = (target: HTMLElement): void => {
   const timers = slideTimers.get(target) ?? []
@@ -126,7 +188,7 @@ const clearSlideStyles = (target: HTMLElement): void => {
   }
 }
 
-/* SLIDE UP */
+// SLIDE UP
 const slideUp = (target: HTMLElement, duration = 500) => {
   cancelSlide(target)
 
@@ -159,7 +221,7 @@ const slideUp = (target: HTMLElement, duration = 500) => {
   slideTimers.set(target, [stepTimer, cleanupTimer])
 }
 
-/* SLIDE DOWN */
+// SLIDE DOWN
 const slideDown = (target: HTMLElement, duration = 500) => {
   cancelSlide(target)
   // Drop inline styles a cancelled slideUp may have left behind (height: 0,
@@ -206,7 +268,7 @@ const slideDown = (target: HTMLElement, duration = 500) => {
   slideTimers.set(target, [stepTimer, cleanupTimer])
 }
 
-/* TOGGLE */
+// TOGGLE
 const slideToggle = (target: HTMLElement, duration = 500) => {
   if (globalThis.getComputedStyle(target).display === 'none') {
     slideDown(target, duration)
@@ -219,6 +281,8 @@ const slideToggle = (target: HTMLElement, duration = 500) => {
 export {
   onDOMContentLoaded,
   getLifecycleSignal,
+  initialize,
+  teardown,
   slideUp,
   slideDown,
   slideToggle,