admin-lte 4.0.4 → 4.1.0

package/src/ts/base-component.ts

@@ -0,0 +1,84 @@
+/**
+ * --------------------------------------------
+ * @file AdminLTE base-component.ts
+ * @description Shared component lifecycle for AdminLTE plugins: a per-element
+ * instance registry (getInstance / getOrCreateInstance / dispose) and a
+ * consistent custom-event contract, mirroring Bootstrap's component API.
+ * @license MIT
+ * --------------------------------------------
+ */
+
+/**
+ * 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.
+ */
+const componentRegistry = new WeakMap<Element, Map<string, BaseComponent>>()
+
+class BaseComponent {
+  static get NAME(): string {
+    throw new Error('Component subclasses must override the static NAME getter.')
+  }
+
+  static get DATA_KEY(): string {
+    return `lte.${this.NAME}`
+  }
+
+  /**
+   * Untyped registry lookup. Every component exposes a typed wrapper
+   * (e.g. CardWidget.getInstance()) built on top of this.
+   */
+  protected static _getInstance(element: Element | null | undefined): BaseComponent | null {
+    if (!element) {
+      return null
+    }
+
+    return componentRegistry.get(element)?.get(this.DATA_KEY) ?? null
+  }
+
+  _element: HTMLElement
+
+  constructor(element: HTMLElement) {
+    this._element = element
+
+    const instances = componentRegistry.get(element) ?? new Map<string, BaseComponent>()
+    componentRegistry.set(element, instances)
+    instances.set((this.constructor as typeof BaseComponent).DATA_KEY, this)
+  }
+
+  /**
+   * Remove this instance from the registry so getInstance() no longer
+   * returns it. Subclasses release their own resources, then call
+   * super.dispose().
+   */
+  dispose(): void {
+    const instances = componentRegistry.get(this._element)
+    instances?.delete((this.constructor as typeof BaseComponent).DATA_KEY)
+
+    if (instances?.size === 0) {
+      componentRegistry.delete(this._element)
+    }
+  }
+}
+
+/**
+ * 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`.
+ */
+const dispatchCustomEvent = <T = undefined>(
+  element: Element,
+  name: string,
+  options: { cancelable?: boolean; detail?: T } = {}
+): CustomEvent<T | undefined> => {
+  const event = new CustomEvent<T | undefined>(name, {
+    bubbles: true,
+    cancelable: options.cancelable ?? false,
+    detail: options.detail
+  })
+
+  element.dispatchEvent(event)
+  return event
+}
+
+export { BaseComponent, dispatchCustomEvent }

package/src/ts/card-widget.ts

@@ -6,8 +6,8 @@
  * --------------------------------------------
  */
 
+import { BaseComponent, dispatchCustomEvent } from './base-component'
 import {
-  onDOMContentLoaded,
   slideUp,
   slideDown
 } from './util/index'
@@ -17,11 +17,18 @@ import {
  * ====================================================
  */
 
-const DATA_KEY = 'lte.card-widget'
-const EVENT_KEY = `.${DATA_KEY}`
+const NAME = 'card-widget'
+const EVENT_KEY = `.lte.${NAME}`
+
+// Cancelable "before" events, dispatched on the card when an action starts.
+const EVENT_COLLAPSE = `collapse${EVENT_KEY}`
+const EVENT_EXPAND = `expand${EVENT_KEY}`
+const EVENT_REMOVE = `remove${EVENT_KEY}`
+
+// "After" events, dispatched on the card when the action has completed.
 const EVENT_COLLAPSED = `collapsed${EVENT_KEY}`
 const EVENT_EXPANDED = `expanded${EVENT_KEY}`
-const EVENT_REMOVE = `remove${EVENT_KEY}`
+const EVENT_REMOVED = `removed${EVENT_KEY}`
 const EVENT_MAXIMIZED = `maximized${EVENT_KEY}`
 const EVENT_MINIMIZED = `minimized${EVENT_KEY}`
 
@@ -53,14 +60,24 @@ const Default: Config = {
   maximizeTrigger: SELECTOR_DATA_MAXIMIZE
 }
 
-class CardWidget {
-  _element: HTMLElement
+class CardWidget extends BaseComponent {
+  static get NAME(): string {
+    return NAME
+  }
+
+  static getInstance(element: Element | null | undefined): CardWidget | null {
+    return this._getInstance(element) as CardWidget | null
+  }
+
+  static getOrCreateInstance(element: HTMLElement, config: Partial<Config> = {}): CardWidget {
+    return this.getInstance(element) ?? new this(element, config)
+  }
+
   _parent: HTMLElement | undefined
-  _clone: HTMLElement | undefined
   _config: Config
 
-  constructor(element: HTMLElement, config: Config) {
-    this._element = element
+  constructor(element: HTMLElement, config: Partial<Config> = {}) {
+    super(element)
     this._parent = element.closest(SELECTOR_CARD) as HTMLElement | undefined
 
     if (element.classList.contains(CLASS_NAME_CARD)) {
@@ -71,76 +88,87 @@ class CardWidget {
   }
 
   collapse() {
-    const event = new Event(EVENT_COLLAPSED)
+    if (!this._parent) {
+      return
+    }
 
-    if (this._parent) {
-      this._parent.classList.add(CLASS_NAME_COLLAPSING)
-      this._parent.classList.remove(CLASS_NAME_EXPANDING)
+    if (dispatchCustomEvent(this._parent, EVENT_COLLAPSE, { cancelable: true }).defaultPrevented) {
+      return
+    }
 
-      // Only target direct children to avoid affecting nested cards
-      const elm = this._parent?.querySelectorAll(`:scope > ${SELECTOR_CARD_BODY}, :scope > ${SELECTOR_CARD_FOOTER}`)
+    this._parent.classList.add(CLASS_NAME_COLLAPSING)
+    this._parent.classList.remove(CLASS_NAME_EXPANDING)
 
-      elm.forEach(el => {
-        if (el instanceof HTMLElement) {
-          slideUp(el, this._config.animationSpeed)
-        }
-      })
+    // Only target direct children to avoid affecting nested cards
+    const elm = this._parent.querySelectorAll(`:scope > ${SELECTOR_CARD_BODY}, :scope > ${SELECTOR_CARD_FOOTER}`)
 
-      setTimeout(() => {
-        // Guard against a stale timer: if expand() ran while this collapse
-        // was still animating, the card must not end up marked collapsed.
-        if (this._parent?.classList.contains(CLASS_NAME_COLLAPSING)) {
-          this._parent.classList.add(CLASS_NAME_COLLAPSED)
-          this._parent.classList.remove(CLASS_NAME_COLLAPSING)
-        }
-      }, this._config.animationSpeed)
-    }
+    elm.forEach(el => {
+      if (el instanceof HTMLElement) {
+        slideUp(el, this._config.animationSpeed)
+      }
+    })
 
-    this._element?.dispatchEvent(event)
+    setTimeout(() => {
+      // Guard against a stale timer: if expand() ran while this collapse
+      // was still animating, the card must not end up marked collapsed.
+      if (this._parent?.classList.contains(CLASS_NAME_COLLAPSING)) {
+        this._parent.classList.add(CLASS_NAME_COLLAPSED)
+        this._parent.classList.remove(CLASS_NAME_COLLAPSING)
+        dispatchCustomEvent(this._parent, EVENT_COLLAPSED)
+      }
+    }, this._config.animationSpeed)
   }
 
   expand() {
-    const event = new Event(EVENT_EXPANDED)
+    if (!this._parent) {
+      return
+    }
 
-    if (this._parent) {
-      this._parent.classList.add(CLASS_NAME_EXPANDING)
-      this._parent.classList.remove(CLASS_NAME_COLLAPSING, CLASS_NAME_COLLAPSED)
+    if (dispatchCustomEvent(this._parent, EVENT_EXPAND, { cancelable: true }).defaultPrevented) {
+      return
+    }
 
-      // Only target direct children to avoid affecting nested cards
-      const elm = this._parent?.querySelectorAll(`:scope > ${SELECTOR_CARD_BODY}, :scope > ${SELECTOR_CARD_FOOTER}`)
+    this._parent.classList.add(CLASS_NAME_EXPANDING)
+    this._parent.classList.remove(CLASS_NAME_COLLAPSING, CLASS_NAME_COLLAPSED)
 
-      elm.forEach(el => {
-        if (el instanceof HTMLElement) {
-          slideDown(el, this._config.animationSpeed)
-        }
-      })
+    // Only target direct children to avoid affecting nested cards
+    const elm = this._parent.querySelectorAll(`:scope > ${SELECTOR_CARD_BODY}, :scope > ${SELECTOR_CARD_FOOTER}`)
 
-      setTimeout(() => {
-        // Same stale-timer guard as collapse(), in the other direction.
-        if (this._parent?.classList.contains(CLASS_NAME_EXPANDING)) {
-          this._parent.classList.remove(CLASS_NAME_EXPANDING)
-        }
-      }, this._config.animationSpeed)
-    }
+    elm.forEach(el => {
+      if (el instanceof HTMLElement) {
+        slideDown(el, this._config.animationSpeed)
+      }
+    })
 
-    this._element?.dispatchEvent(event)
+    setTimeout(() => {
+      // Same stale-timer guard as collapse(), in the other direction.
+      if (this._parent?.classList.contains(CLASS_NAME_EXPANDING)) {
+        this._parent.classList.remove(CLASS_NAME_EXPANDING)
+        dispatchCustomEvent(this._parent, EVENT_EXPANDED)
+      }
+    }, this._config.animationSpeed)
   }
 
   remove() {
-    const event = new Event(EVENT_REMOVE)
-
-    if (this._parent) {
-      const parent = this._parent
-      slideUp(parent, this._config.animationSpeed)
+    if (!this._parent) {
+      return
+    }
 
-      // Actually remove the card once the animation finishes — hiding it
-      // would keep its form fields submitting and its ids in the document.
-      setTimeout(() => {
-        parent.remove()
-      }, this._config.animationSpeed)
+    if (dispatchCustomEvent(this._parent, EVENT_REMOVE, { cancelable: true }).defaultPrevented) {
+      return
     }
 
-    this._element?.dispatchEvent(event)
+    const parent = this._parent
+    slideUp(parent, this._config.animationSpeed)
+
+    // Actually remove the card once the animation finishes — hiding it
+    // would keep its form fields submitting and its ids in the document.
+    // `removed` is dispatched just before detachment so it can still bubble.
+    setTimeout(() => {
+      dispatchCustomEvent(parent, EVENT_REMOVED)
+      parent.remove()
+      this.dispose()
+    }, this._config.animationSpeed)
   }
 
   toggle() {
@@ -155,8 +183,6 @@ class CardWidget {
   }
 
   maximize() {
-    const event = new Event(EVENT_MAXIMIZED)
-
     if (this._parent) {
       this._parent.style.height = `${this._parent.offsetHeight}px`
       this._parent.style.width = `${this._parent.offsetWidth}px`
@@ -175,16 +201,14 @@ class CardWidget {
           if (this._parent.classList.contains(CLASS_NAME_COLLAPSED)) {
             this._parent.classList.add(CLASS_NAME_WAS_COLLAPSED)
           }
+
+          dispatchCustomEvent(this._parent, EVENT_MAXIMIZED)
         }
       }, 150)
     }
-
-    this._element?.dispatchEvent(event)
   }
 
   minimize() {
-    const event = new Event(EVENT_MINIMIZED)
-
     if (this._parent) {
       this._parent.style.height = 'auto'
       this._parent.style.width = 'auto'
@@ -204,6 +228,8 @@ class CardWidget {
             this._parent.classList.remove(CLASS_NAME_WAS_COLLAPSED)
           }
 
+          dispatchCustomEvent(this._parent, EVENT_MINIMIZED)
+
           // Drop the inline sizing/transition once the restore transition has
           // finished so the card doesn't carry stale styles forever.
           setTimeout(() => {
@@ -214,8 +240,6 @@ class CardWidget {
         }
       }, 10)
     }
-
-    this._element?.dispatchEvent(event)
   }
 
   toggleMaximize() {
@@ -232,44 +256,44 @@ class CardWidget {
  *
  * Data Api implementation
  * ====================================================
+ * A single delegated listener on `document` handles all card toggles — so
+ * cards inserted later (AJAX, Turbo Frames) work without re-initialisation,
+ * and the listener itself survives Turbo's <body> swaps.
  */
 
-onDOMContentLoaded(() => {
-  const collapseBtn = document.querySelectorAll(SELECTOR_DATA_COLLAPSE)
-
-  // Use currentTarget (the [data-lte-toggle] button itself), not target:
-  // clicking the <i> icon inside the button would otherwise make the widget's
-  // events fire on the icon instead of the button.
-  collapseBtn.forEach(btn => {
-    btn.addEventListener('click', event => {
-      event.preventDefault()
-      const target = event.currentTarget as HTMLElement
-      const data = new CardWidget(target, Default)
-      data.toggle()
-    })
-  })
+document.addEventListener('click', event => {
+  const target = event.target
 
-  const removeBtn = document.querySelectorAll(SELECTOR_DATA_REMOVE)
+  if (!(target instanceof Element)) {
+    return
+  }
 
-  removeBtn.forEach(btn => {
-    btn.addEventListener('click', event => {
-      event.preventDefault()
-      const target = event.currentTarget as HTMLElement
-      const data = new CardWidget(target, Default)
-      data.remove()
-    })
-  })
+  const collapseTrigger = target.closest(SELECTOR_DATA_COLLAPSE)
+  const removeTrigger = target.closest(SELECTOR_DATA_REMOVE)
+  const maximizeTrigger = target.closest(SELECTOR_DATA_MAXIMIZE)
+  const trigger = collapseTrigger ?? removeTrigger ?? maximizeTrigger
 
-  const maxBtn = document.querySelectorAll(SELECTOR_DATA_MAXIMIZE)
+  if (!trigger) {
+    return
+  }
 
-  maxBtn.forEach(btn => {
-    btn.addEventListener('click', event => {
-      event.preventDefault()
-      const target = event.currentTarget as HTMLElement
-      const data = new CardWidget(target, Default)
-      data.toggleMaximize()
-    })
-  })
+  event.preventDefault()
+
+  const card = trigger.closest(SELECTOR_CARD) as HTMLElement | null
+
+  if (!card) {
+    return
+  }
+
+  const widget = CardWidget.getOrCreateInstance(card)
+
+  if (collapseTrigger) {
+    widget.toggle()
+  } else if (removeTrigger) {
+    widget.remove()
+  } else {
+    widget.toggleMaximize()
+  }
 })
 
 export default CardWidget

package/src/ts/color-mode.ts

@@ -0,0 +1,174 @@
+/**
+ * --------------------------------------------
+ * @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.
+ *
+ * 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.
+ * @license MIT
+ * --------------------------------------------
+ */
+
+import { getLifecycleSignal, onDOMContentLoaded } from './util/index'
+
+/**
+ * Constants
+ * ====================================================
+ */
+
+const DATA_KEY = 'lte.color-mode'
+const EVENT_KEY = `.${DATA_KEY}`
+const EVENT_CHANGED = `changed${EVENT_KEY}`
+
+const STORAGE_KEY = 'lte-theme'
+
+const SELECTOR_TOGGLE = '[data-bs-theme-value]'
+const SELECTOR_ICON = '[data-lte-theme-icon]'
+
+type Theme = 'light' | 'dark' | 'auto'
+
+/**
+ * Class Definition
+ * ====================================================
+ */
+
+class ColorMode {
+  /**
+   * Read the persisted theme choice, or null when nothing was stored or
+   * localStorage is unavailable (private mode, sandboxed iframe).
+   */
+  getStoredTheme(): Theme | null {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY)
+      return stored && ['light', 'dark', 'auto'].includes(stored) ? stored as Theme : null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * The user's effective choice: the stored theme, falling back to the OS
+   * preference.
+   */
+  getPreferredTheme(): Theme {
+    const stored = this.getStoredTheme()
+    if (stored) {
+      return stored
+    }
+
+    return this._prefersDark() ? 'dark' : 'light'
+  }
+
+  /**
+   * Resolve "auto" against the OS preference.
+   */
+  resolveTheme(theme: Theme): 'light' | 'dark' {
+    if (theme === 'auto') {
+      return this._prefersDark() ? 'dark' : 'light'
+    }
+
+    return theme
+  }
+
+  /**
+   * Apply a theme and persist the choice. Dispatches
+   * `changed.lte.color-mode` on the document with { theme, resolved }.
+   */
+  setTheme(theme: Theme): void {
+    try {
+      localStorage.setItem(STORAGE_KEY, theme)
+    } catch {
+      // localStorage may be unavailable; the theme still applies for this page.
+    }
+
+    this._applyTheme(theme)
+    this._showActiveTheme(theme)
+
+    document.dispatchEvent(new CustomEvent(EVENT_CHANGED, {
+      detail: { theme, resolved: this.resolveTheme(theme) }
+    }))
+  }
+
+  /**
+   * Apply without persisting — used on init and when the OS preference
+   * changes while in "auto" mode.
+   */
+  _applyTheme(theme: Theme): void {
+    const resolved = this.resolveTheme(theme)
+    document.documentElement.setAttribute('data-bs-theme', resolved)
+    document.documentElement.style.colorScheme = resolved
+  }
+
+  _prefersDark(): boolean {
+    return globalThis.matchMedia('(prefers-color-scheme: dark)').matches
+  }
+
+  /**
+   * Sync the [data-bs-theme-value] toggles (active state, pressed state,
+   * check mark) and the [data-lte-theme-icon] indicator icons.
+   */
+  _showActiveTheme(theme: Theme): void {
+    document.querySelectorAll(SELECTOR_TOGGLE).forEach(toggle => {
+      const isActive = toggle.getAttribute('data-bs-theme-value') === theme
+      toggle.classList.toggle('active', isActive)
+      toggle.setAttribute('aria-pressed', String(isActive))
+      toggle.querySelector('.bi-check-lg')?.classList.toggle('d-none', !isActive)
+    })
+
+    document.querySelectorAll(SELECTOR_ICON).forEach(icon => {
+      icon.classList.toggle('d-none', (icon as HTMLElement).dataset.lteThemeIcon !== theme)
+    })
+  }
+
+  /**
+   * Apply the preferred theme and sync the UI without persisting anything.
+   */
+  init(): void {
+    const theme = this.getPreferredTheme()
+    this._applyTheme(theme)
+    this._showActiveTheme(theme)
+  }
+}
+
+/**
+ * Data API implementation
+ * ====================================================
+ * Toggle clicks are delegated on `document`, so switcher buttons added after
+ * load work and the listener survives Turbo's <body> swaps. The class is
+ * stateless — everything lives in localStorage and the DOM.
+ */
+
+document.addEventListener('click', event => {
+  const target = event.target
+
+  if (!(target instanceof Element)) {
+    return
+  }
+
+  const toggle = target.closest(SELECTOR_TOGGLE)
+  const theme = toggle?.getAttribute('data-bs-theme-value') as Theme | null
+
+  if (theme) {
+    new ColorMode().setTheme(theme)
+  }
+})
+
+onDOMContentLoaded(() => {
+  const colorMode = new ColorMode()
+  colorMode.init()
+
+  // Follow the OS while no explicit choice (or "auto") is stored.
+  globalThis.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+    const stored = colorMode.getStoredTheme()
+    if (!stored || stored === 'auto') {
+      colorMode._applyTheme('auto')
+      colorMode._showActiveTheme(stored ?? 'auto')
+    }
+  }, { signal: getLifecycleSignal() })
+})
+
+export default ColorMode

package/src/ts/direct-chat.ts

@@ -6,17 +6,15 @@
  * --------------------------------------------
  */
 
-import {
-  onDOMContentLoaded
-} from './util/index'
+import { BaseComponent, dispatchCustomEvent } from './base-component'
 
 /**
  * Constants
  * ====================================================
  */
 
-const DATA_KEY = 'lte.direct-chat'
-const EVENT_KEY = `.${DATA_KEY}`
+const NAME = 'direct-chat'
+const EVENT_KEY = `.lte.${NAME}`
 const EVENT_EXPANDED = `expanded${EVENT_KEY}`
 const EVENT_COLLAPSED = `collapsed${EVENT_KEY}`
 
@@ -30,25 +28,26 @@ const CLASS_NAME_DIRECT_CHAT_OPEN = 'direct-chat-contacts-open'
  * ====================================================
  */
 
-class DirectChat {
-  _element: HTMLElement
-  constructor(element: HTMLElement) {
-    this._element = element
+class DirectChat extends BaseComponent {
+  static get NAME(): string {
+    return NAME
+  }
+
+  static getInstance(element: Element | null | undefined): DirectChat | null {
+    return this._getInstance(element) as DirectChat | null
+  }
+
+  static getOrCreateInstance(element: HTMLElement): DirectChat {
+    return this.getInstance(element) ?? new this(element)
   }
 
   toggle(): void {
     if (this._element.classList.contains(CLASS_NAME_DIRECT_CHAT_OPEN)) {
-      const event = new Event(EVENT_COLLAPSED)
-
       this._element.classList.remove(CLASS_NAME_DIRECT_CHAT_OPEN)
-
-      this._element.dispatchEvent(event)
+      dispatchCustomEvent(this._element, EVENT_COLLAPSED)
     } else {
-      const event = new Event(EVENT_EXPANDED)
-
       this._element.classList.add(CLASS_NAME_DIRECT_CHAT_OPEN)
-
-      this._element.dispatchEvent(event)
+      dispatchCustomEvent(this._element, EVENT_EXPANDED)
     }
   }
 }
@@ -57,23 +56,30 @@ class DirectChat {
  *
  * Data Api implementation
  * ====================================================
+ * One delegated listener on `document`: chat panes inserted later work, and
+ * the listener survives Turbo's <body> swaps.
  */
 
-onDOMContentLoaded(() => {
-  const button = document.querySelectorAll(SELECTOR_DATA_TOGGLE)
-
-  button.forEach(btn => {
-    btn.addEventListener('click', event => {
-      event.preventDefault()
-      const target = event.target as HTMLElement
-      const chatPane = target.closest(SELECTOR_DIRECT_CHAT) as HTMLElement | undefined
-
-      if (chatPane) {
-        const data = new DirectChat(chatPane)
-        data.toggle()
-      }
-    })
-  })
+document.addEventListener('click', event => {
+  const target = event.target
+
+  if (!(target instanceof Element)) {
+    return
+  }
+
+  const trigger = target.closest(SELECTOR_DATA_TOGGLE)
+
+  if (!trigger) {
+    return
+  }
+
+  event.preventDefault()
+
+  const chatPane = trigger.closest(SELECTOR_DIRECT_CHAT) as HTMLElement | null
+
+  if (chatPane) {
+    DirectChat.getOrCreateInstance(chatPane).toggle()
+  }
 })
 
 export default DirectChat