admin-lte 4.1.0 → 4.2.0

package/src/ts/adminlte.ts

@@ -1,4 +1,4 @@
-import { onDOMContentLoaded } from './util/index.js'
+import { initialize, teardown, onDOMContentLoaded } from './util/index.js'
 import Layout from './layout.js'
 import CardWidget from './card-widget.js'
 import Treeview from './treeview.js'
@@ -9,7 +9,7 @@ import ColorMode from './color-mode.js'
 import { initAccessibility } from './accessibility.js'
 
 /**
- * AdminLTE v4.1.0
+ * AdminLTE v4.2.0
  * Author: Colorlib
  * Website: AdminLTE.io <https://adminlte.io>
  * License: Open source - MIT <https://opensource.org/licenses/MIT>
@@ -40,5 +40,7 @@ export {
   FullScreen,
   PushMenu,
   ColorMode,
-  initAccessibility
+  initAccessibility,
+  initialize,
+  teardown
 }

package/src/ts/base-component.ts

@@ -9,17 +9,25 @@
  */
 
 /**
- * element -> (data key -> component instance). WeakMap keys don't prevent
- * garbage collection, so instances die with their elements — important under
- * Hotwired Turbo, which swaps the whole <body> on navigation.
+ * Component registry: element -> (data key -> component instance). A single
+ * element can host several components at once, each stored under its own
+ * DATA_KEY. WeakMap keys don't prevent garbage collection, so instances die
+ * with their elements — important under Hotwired Turbo, which swaps the whole
+ * <body> on navigation.
  */
 const componentRegistry = new WeakMap<Element, Map<string, BaseComponent>>()
 
 class BaseComponent {
+  /**
+   * Subclasses must override this getter to declare their own name.
+   */
   static get NAME(): string {
     throw new Error('Component subclasses must override the static NAME getter.')
   }
 
+  /**
+   * Key this component is registered under: `lte.<name>`.
+   */
   static get DATA_KEY(): string {
     return `lte.${this.NAME}`
   }
@@ -27,6 +35,9 @@ class BaseComponent {
   /**
    * Untyped registry lookup. Every component exposes a typed wrapper
    * (e.g. CardWidget.getInstance()) built on top of this.
+   *
+   * @param element The element to look up.
+   * @returns The instance for this component, or null if there is none.
    */
   protected static _getInstance(element: Element | null | undefined): BaseComponent | null {
     if (!element) {
@@ -36,8 +47,17 @@ class BaseComponent {
     return componentRegistry.get(element)?.get(this.DATA_KEY) ?? null
   }
 
+  /**
+   * The element this instance is attached to.
+   */
   _element: HTMLElement
 
+  /**
+   * Attach a new instance to the given element and register it under the
+   * subclass's DATA_KEY.
+   *
+   * @param element The element to attach this instance to.
+   */
   constructor(element: HTMLElement) {
     this._element = element
 
@@ -55,6 +75,7 @@ class BaseComponent {
     const instances = componentRegistry.get(this._element)
     instances?.delete((this.constructor as typeof BaseComponent).DATA_KEY)
 
+    // Drop the element's entry once it holds no components at all.
     if (instances?.size === 0) {
       componentRegistry.delete(this._element)
     }
@@ -65,6 +86,12 @@ class BaseComponent {
  * Dispatch a namespaced custom event that bubbles — so applications can
  * listen once on `document` — and can optionally carry a payload or be
  * canceled. Returns the event so callers can check `defaultPrevented`.
+ *
+ * @param element The element to dispatch the event on.
+ * @param name The namespaced event name, e.g. `collapse.lte.push-menu`.
+ * @param options `cancelable` opts the event into preventDefault(); `detail`
+ *   is the payload handed to listeners.
+ * @returns The dispatched event, after listeners have run.
  */
 const dispatchCustomEvent = <T = undefined>(
   element: Element,

package/src/ts/color-mode.ts

@@ -2,13 +2,19 @@
  * --------------------------------------------
  * @file AdminLTE color-mode.ts
  * @description Color mode (light/dark/auto) switcher for AdminLTE.
- * Persists the choice in localStorage, follows the OS preference in
- * "auto" mode, and keeps [data-bs-theme-value] toggles and
- * [data-lte-theme-icon] indicator icons in sync.
+ * Resolves the theme from, in order: the visitor's stored choice, the theme
+ * the page itself declared in <html data-bs-theme="…">, and finally the OS
+ * preference. Keeps [data-bs-theme-value] toggles and [data-lte-theme-icon]
+ * indicator icons in sync.
  *
  * Ships in the bundle so applications no longer need to copy the demo's
  * inline script. The tiny no-flash snippet in <head> (see _head.astro)
- * remains inline by design — it must run before first paint.
+ * remains inline by design — it must run before first paint. That snippet
+ * flags the values it computes itself with [data-lte-theme-resolved], so a
+ * theme authored in the markup can be told apart from one it resolved.
+ *
+ * Applications with their own theming opt out entirely with
+ * <html data-lte-color-mode="off">.
  * @license MIT
  * --------------------------------------------
  */
@@ -26,11 +32,59 @@ const EVENT_CHANGED = `changed${EVENT_KEY}`
 
 const STORAGE_KEY = 'lte-theme'
 
-const SELECTOR_TOGGLE = '[data-bs-theme-value]'
+const ATTRIBUTE_THEME = 'data-bs-theme'
+const ATTRIBUTE_TOGGLE = 'data-bs-theme-value'
+const ATTRIBUTE_DISABLED = 'data-lte-color-mode'
+const ATTRIBUTE_RESOLVED = 'data-lte-theme-resolved'
+
+const SELECTOR_TOGGLE = `[${ATTRIBUTE_TOGGLE}]`
 const SELECTOR_ICON = '[data-lte-theme-icon]'
 
 type Theme = 'light' | 'dark' | 'auto'
 
+const THEMES = new Set<string>(['light', 'dark', 'auto'])
+
+const isValidTheme = (value: string): value is Theme => THEMES.has(value)
+
+/**
+ * Applications with their own theming take over by adding
+ * `data-lte-color-mode="off"` to <html>: ColorMode then never writes
+ * `data-bs-theme` — not on load, not on a toggle click, not when the OS
+ * preference changes. This is also the escape hatch for custom Bootstrap
+ * themes, whose names ColorMode cannot resolve (#6084).
+ *
+ * Read live rather than captured, so it can be flipped at runtime.
+ */
+const isDisabled = (): boolean =>
+  document.documentElement.getAttribute(ATTRIBUTE_DISABLED) === 'off'
+
+/**
+ * The theme the page itself declared in <html data-bs-theme="…">, or null when
+ * it declared none.
+ *
+ * Captured once, at module evaluation, because the attribute is both an input
+ * and an output: after the first `_applyTheme()` it holds ColorMode's own
+ * write, which must not be mistaken for the page's intent on a later lifecycle
+ * pass (Turbo, `initialize()`). Reading it here runs before any of those.
+ *
+ * The pre-paint snippet in <head> writes before this module is even fetched,
+ * so it marks the values it computed itself with [data-lte-theme-resolved] —
+ * those are not authored, and are ignored.
+ */
+const readMarkupTheme = (): Theme | null => {
+  const { documentElement } = document
+
+  if (documentElement.hasAttribute(ATTRIBUTE_RESOLVED)) {
+    return null
+  }
+
+  const declared = documentElement.getAttribute(ATTRIBUTE_THEME)
+
+  return declared && isValidTheme(declared) ? declared : null
+}
+
+const MARKUP_THEME = readMarkupTheme()
+
 /**
  * Class Definition
  * ====================================================
@@ -44,20 +98,32 @@ class ColorMode {
   getStoredTheme(): Theme | null {
     try {
       const stored = localStorage.getItem(STORAGE_KEY)
-      return stored && ['light', 'dark', 'auto'].includes(stored) ? stored as Theme : null
+      return stored && isValidTheme(stored) ? stored : null
     } catch {
       return null
     }
   }
 
   /**
-   * The user's effective choice: the stored theme, falling back to the OS
-   * preference.
+   * The theme declared in the markup, for applications that render it
+   * server-side from a cookie or a user record. Null when the page declared
+   * none, or when the value is a custom Bootstrap theme ColorMode cannot
+   * resolve — see `isDisabled` for those.
+   */
+  getMarkupTheme(): Theme | null {
+    return MARKUP_THEME
+  }
+
+  /**
+   * The user's effective choice: the stored theme, then the theme declared in
+   * the markup, falling back to the OS preference. Storage comes first because
+   * it is the visitor's own click on this device; markup is only the default
+   * the page shipped with.
    */
   getPreferredTheme(): Theme {
-    const stored = this.getStoredTheme()
-    if (stored) {
-      return stored
+    const preferred = this.getStoredTheme() ?? this.getMarkupTheme()
+    if (preferred) {
+      return preferred
     }
 
     return this._prefersDark() ? 'dark' : 'light'
@@ -99,10 +165,13 @@ class ColorMode {
    */
   _applyTheme(theme: Theme): void {
     const resolved = this.resolveTheme(theme)
-    document.documentElement.setAttribute('data-bs-theme', resolved)
+    document.documentElement.setAttribute(ATTRIBUTE_THEME, resolved)
     document.documentElement.style.colorScheme = resolved
   }
 
+  /**
+   * Whether the OS preference is currently dark.
+   */
   _prefersDark(): boolean {
     return globalThis.matchMedia('(prefers-color-scheme: dark)').matches
   }
@@ -113,7 +182,7 @@ class ColorMode {
    */
   _showActiveTheme(theme: Theme): void {
     document.querySelectorAll(SELECTOR_TOGGLE).forEach(toggle => {
-      const isActive = toggle.getAttribute('data-bs-theme-value') === theme
+      const isActive = toggle.getAttribute(ATTRIBUTE_TOGGLE) === theme
       toggle.classList.toggle('active', isActive)
       toggle.setAttribute('aria-pressed', String(isActive))
       toggle.querySelector('.bi-check-lg')?.classList.toggle('d-none', !isActive)
@@ -128,6 +197,10 @@ class ColorMode {
    * Apply the preferred theme and sync the UI without persisting anything.
    */
   init(): void {
+    if (isDisabled()) {
+      return
+    }
+
     const theme = this.getPreferredTheme()
     this._applyTheme(theme)
     this._showActiveTheme(theme)
@@ -145,14 +218,14 @@ class ColorMode {
 document.addEventListener('click', event => {
   const target = event.target
 
-  if (!(target instanceof Element)) {
+  if (!(target instanceof Element) || isDisabled()) {
     return
   }
 
   const toggle = target.closest(SELECTOR_TOGGLE)
-  const theme = toggle?.getAttribute('data-bs-theme-value') as Theme | null
+  const theme = toggle?.getAttribute(ATTRIBUTE_TOGGLE)
 
-  if (theme) {
+  if (theme && isValidTheme(theme)) {
     new ColorMode().setTheme(theme)
   }
 })
@@ -161,12 +234,19 @@ onDOMContentLoaded(() => {
   const colorMode = new ColorMode()
   colorMode.init()
 
-  // Follow the OS while no explicit choice (or "auto") is stored.
+  // Follow the OS only while the OS *is* the effective choice: nothing stored
+  // and nothing declared in the markup, or an explicit "auto". A theme the
+  // page declared is a preference too, and outlives an OS change (#6093).
   globalThis.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
-    const stored = colorMode.getStoredTheme()
-    if (!stored || stored === 'auto') {
+    if (isDisabled()) {
+      return
+    }
+
+    const preferred = colorMode.getStoredTheme() ?? colorMode.getMarkupTheme()
+
+    if (!preferred || preferred === 'auto') {
       colorMode._applyTheme('auto')
-      colorMode._showActiveTheme(stored ?? 'auto')
+      colorMode._showActiveTheme(preferred ?? 'auto')
     }
   }, { signal: getLifecycleSignal() })
 })

package/src/ts/push-menu.ts

@@ -80,16 +80,37 @@ class PushMenu extends BaseComponent {
     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
 
+  /**
+   * @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 }
@@ -158,6 +179,8 @@ class PushMenu extends BaseComponent {
    * 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
     }
@@ -341,12 +364,12 @@ class PushMenu extends BaseComponent {
 
     // 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()
     }
   }
@@ -446,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) {
@@ -464,12 +494,12 @@ onDOMContentLoaded(() => {
     }
 
     overlayTouchMoved = false
-  }, { passive: false })
+  }, { passive: false, signal: overlaySignal })
 
   sidebarOverlay.addEventListener('click', event => {
     event.preventDefault()
     pushMenu.collapse()
-  })
+  }, { signal: overlaySignal })
 })
 
 export default PushMenu

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()
@@ -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,