admin-lte 4.1.0 → 4.3.1

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/sidebar-search.ts

@@ -0,0 +1,252 @@
+/**
+ * --------------------------------------------
+ * @file AdminLTE sidebar-search.ts
+ * @description Live filter for the sidebar menu.
+ * @license MIT
+ * --------------------------------------------
+ */
+
+import { BaseComponent, dispatchCustomEvent } from './base-component'
+import { onDOMContentLoaded } from './util/index'
+
+/**
+ * Constants
+ * ============================================================================
+ */
+const NAME = 'sidebar-search'
+const EVENT_KEY = `.lte.${NAME}`
+const EVENT_FILTERED = `filtered${EVENT_KEY}`
+
+const CLASS_NAME_MENU_OPEN = 'menu-open'
+
+const SELECTOR_DATA_TOGGLE = '[data-lte-toggle="sidebar-search"]'
+const SELECTOR_SIDEBAR = '.app-sidebar'
+const SELECTOR_MENU = '.sidebar-menu'
+const SELECTOR_NAV_ITEM = '.nav-item'
+const SELECTOR_NAV_HEADER = '.nav-header'
+const SELECTOR_NAV_LINK = ':scope > .nav-link'
+const SELECTOR_TREEVIEW_MENU = ':scope > .nav-treeview'
+const SELECTOR_EMPTY_STATE = '[data-lte-search-empty]'
+
+/**
+ * A submenu's resting state, captured before the first keystroke so clearing
+ * the field can put the menu back exactly as the user left it. The inline
+ * `display` matters as well as the class: Treeview's slide animation writes
+ * one, and it would otherwise win over `.menu-open > .nav-treeview`.
+ */
+type SubmenuState = {
+  open: boolean;
+  display: string;
+}
+
+const submenuOf = (item: HTMLElement): HTMLElement | null =>
+  item.querySelector<HTMLElement>(SELECTOR_TREEVIEW_MENU)
+
+const setOpen = (item: HTMLElement, submenu: HTMLElement, open: boolean, display: string): void => {
+  item.classList.toggle(CLASS_NAME_MENU_OPEN, open)
+  item.querySelector(SELECTOR_NAV_LINK)?.setAttribute('aria-expanded', String(open))
+  submenu.style.display = display
+}
+
+/**
+ * Class Definition
+ * ============================================================================
+ */
+class SidebarSearch extends BaseComponent {
+  static get NAME(): string {
+    return NAME
+  }
+
+  static getInstance(element: Element | null | undefined): SidebarSearch | null {
+    return this._getInstance(element) as SidebarSearch | null
+  }
+
+  static getOrCreateInstance(element: HTMLElement): SidebarSearch {
+    return this.getInstance(element) ?? new this(element)
+  }
+
+  _menu: HTMLElement | null
+  _emptyState: HTMLElement | null
+  _snapshot: Map<HTMLElement, SubmenuState> | null = null
+
+  constructor(element: HTMLElement) {
+    super(element)
+
+    // `data-lte-target` names the menu explicitly; without it, the nearest
+    // sidebar's menu is used, which covers the single-sidebar default.
+    const target = element.dataset.lteTarget
+    const scope = element.closest(SELECTOR_SIDEBAR) ?? document
+
+    this._menu = target ?
+      document.querySelector<HTMLElement>(target) :
+      scope.querySelector<HTMLElement>(SELECTOR_MENU)
+    this._emptyState = scope.querySelector<HTMLElement>(SELECTOR_EMPTY_STATE)
+  }
+
+  /**
+   * Show only the menu entries matching `term`, expanding whatever has to be
+   * expanded to reveal them. An empty term restores the menu.
+   *
+   * @param term The text to match against nav-link labels, case-insensitively.
+   */
+  search(term: string): void {
+    const menu = this._menu
+
+    if (!menu) {
+      return
+    }
+
+    const query = term.trim().toLowerCase()
+
+    if (!query) {
+      this.clear()
+      return
+    }
+
+    this._snapshot ??= this._takeSnapshot(menu)
+
+    const items = [...menu.querySelectorAll<HTMLElement>(SELECTOR_NAV_ITEM)]
+    const matched = new Set<HTMLElement>()
+
+    for (const item of items) {
+      const label = item.querySelector(SELECTOR_NAV_LINK)?.textContent?.replace(/\s+/g, ' ').trim().toLowerCase()
+
+      if (label?.includes(query)) {
+        matched.add(item)
+      }
+    }
+
+    // Deepest-first, so by the time a parent is reached its children have
+    // already been hidden or kept and it can simply look for a survivor.
+    for (let index = items.length - 1; index >= 0; index--) {
+      const item = items[index]
+      item.hidden = !(matched.has(item) || item.querySelector(`${SELECTOR_NAV_ITEM}:not([hidden])`))
+    }
+
+    // A group whose own name matched keeps its whole subtree — otherwise
+    // expanding it would lead to an empty list.
+    for (const item of matched) {
+      for (const descendant of item.querySelectorAll<HTMLElement>(SELECTOR_NAV_ITEM)) {
+        descendant.hidden = false
+      }
+    }
+
+    let visible = 0
+
+    for (const item of items) {
+      if (!item.hidden) {
+        visible++
+      }
+
+      const submenu = submenuOf(item)
+
+      if (submenu) {
+        const expand = !item.hidden && Boolean(item.querySelector(`${SELECTOR_NAV_ITEM}:not([hidden])`))
+        setOpen(item, submenu, expand, expand ? 'block' : 'none')
+      }
+    }
+
+    // Section headings label groups that are no longer all present.
+    for (const header of menu.querySelectorAll<HTMLElement>(SELECTOR_NAV_HEADER)) {
+      header.hidden = true
+    }
+
+    if (this._emptyState) {
+      this._emptyState.hidden = visible > 0
+    }
+
+    dispatchCustomEvent(this._element, EVENT_FILTERED, { detail: { query, matches: visible } })
+  }
+
+  /**
+   * Drop the filter: every entry becomes visible again and each submenu goes
+   * back to the open/closed state it had before the search started.
+   */
+  clear(): void {
+    const menu = this._menu
+
+    if (!menu) {
+      return
+    }
+
+    for (const item of menu.querySelectorAll<HTMLElement>(`${SELECTOR_NAV_ITEM}, ${SELECTOR_NAV_HEADER}`)) {
+      item.hidden = false
+    }
+
+    if (this._snapshot) {
+      for (const [item, state] of this._snapshot) {
+        const submenu = submenuOf(item)
+
+        if (submenu) {
+          setOpen(item, submenu, state.open, state.display)
+        }
+      }
+
+      this._snapshot = null
+    }
+
+    if (this._emptyState) {
+      this._emptyState.hidden = true
+    }
+
+    dispatchCustomEvent(this._element, EVENT_FILTERED, { detail: { query: '', matches: -1 } })
+  }
+
+  dispose(): void {
+    this.clear()
+    super.dispose()
+  }
+
+  _takeSnapshot(menu: HTMLElement): Map<HTMLElement, SubmenuState> {
+    const snapshot = new Map<HTMLElement, SubmenuState>()
+
+    for (const item of menu.querySelectorAll<HTMLElement>(SELECTOR_NAV_ITEM)) {
+      const submenu = submenuOf(item)
+
+      if (submenu) {
+        snapshot.set(item, {
+          open: item.classList.contains(CLASS_NAME_MENU_OPEN),
+          display: submenu.style.display
+        })
+      }
+    }
+
+    return snapshot
+  }
+}
+
+/**
+ * Data Api implementation
+ * ============================================================================
+ * Both listeners are delegated on `document`, so a sidebar rendered after load
+ * (Turbo Frame, client-side router) needs no re-initialisation.
+ */
+
+document.addEventListener('input', event => {
+  const target = event.target
+
+  if (target instanceof HTMLInputElement && target.matches(SELECTOR_DATA_TOGGLE)) {
+    SidebarSearch.getOrCreateInstance(target).search(target.value)
+  }
+})
+
+document.addEventListener('keydown', event => {
+  const target = event.target
+
+  if (event.key === 'Escape' && target instanceof HTMLInputElement && target.matches(SELECTOR_DATA_TOGGLE)) {
+    target.value = ''
+    SidebarSearch.getOrCreateInstance(target).clear()
+  }
+})
+
+// A field restored with a value by the browser (bfcache, back navigation)
+// should show its filtered menu rather than a menu that disagrees with it.
+onDOMContentLoaded(() => {
+  document.querySelectorAll<HTMLInputElement>(SELECTOR_DATA_TOGGLE).forEach(input => {
+    if (input.value) {
+      SidebarSearch.getOrCreateInstance(input).search(input.value)
+    }
+  })
+})
+
+export default SidebarSearch