admin-lte 4.0.2 → 4.1.0

package/src/scss/adminlte-docs.scss

@@ -0,0 +1,25 @@
+/*!
+ *   AdminLTE v4.0.4 — documentation styles
+ *   Styles for the documentation and FAQ pages only (body.docs-page /
+ *   body.faq-page). Applications never need this file; it is loaded by the
+ *   docs pages in addition to adminlte.css.
+ */
+
+// Bootstrap Configuration
+// ---------------------------------------------------
+@import "bootstrap/scss/functions";
+@import "bootstrap-overrides";
+@import "bootstrap/scss/variables";
+@import "bootstrap/scss/variables-dark";
+@import "bootstrap/scss/maps";
+@import "bootstrap/scss/mixins";
+
+// AdminLTE Configuration
+// ---------------------------------------------------
+@import "variables";
+@import "variables-dark";
+@import "mixins";
+
+// Documentation styles
+// ---------------------------------------------------
+@import "docs";

package/src/scss/adminlte.scss

@@ -1,5 +1,5 @@
 /*!
- *   AdminLTE v4.0.0
+ *   AdminLTE v4.1.0
  *   Author: Colorlib
  *   Website: AdminLTE.io <https://adminlte.io>
  *   License: Open source - MIT <https://opensource.org/licenses/MIT>
@@ -11,7 +11,7 @@
 
 // AdminLTE Configuration
 // ---------------------------------------------------
-@import "bootstrap-variables"; // little modified are here
+@import "bootstrap-overrides"; // AdminLTE's ~10 changes to Bootstrap defaults
 
 // Bootstrap Configuration
 // ---------------------------------------------------
@@ -77,5 +77,6 @@
 // AdminLTE Accessibility Styles - WCAG 2.1 AA Compliance
 @import "accessibility";
 
-// AdminLTE Documentation Styles (only applies to pages with body.docs-page)
-@import "docs";
+// Documentation styles live in their own bundle (adminlte-docs.scss) so
+// applications don't ship them — the docs pages load it in addition to
+// this file.

package/src/scss/pages/_login_and_register.scss

@@ -1,3 +1,5 @@
+@use "sass:map";
+
 //
 // Pages: Login & Register
 //
@@ -28,7 +30,7 @@
 .register-box {
   width: 400px;
 
-  @media (max-width: map-get($grid-breakpoints, sm)) {
+  @media (max-width: map.get($grid-breakpoints, sm)) {
     width: 90%;
     margin-top: .5rem;
   }

package/src/scss/parts/_core.scss

@@ -12,4 +12,3 @@
 @import "../dropdown";
 @import "../callouts";
 @import "../compact-mode";
-@import "../docs";

package/src/ts/accessibility.ts

@@ -3,6 +3,8 @@
  * WCAG 2.1 AA Compliance Features
  */
 
+import { getLifecycleSignal } from './util/index'
+
 export interface AccessibilityConfig {
   announcements: boolean
   skipLinks: boolean
@@ -15,6 +17,9 @@ export class AccessibilityManager {
   private config: AccessibilityConfig
   private liveRegion: HTMLElement | null = null
   private focusHistory: HTMLElement[] = []
+  // Listeners bound to `document` survive Turbo's <body> swap, so they are
+  // registered with this signal and torn down before the next re-init.
+  private readonly signal: AbortSignal = getLifecycleSignal()
 
   constructor(config: Partial<AccessibilityConfig> = {}) {
     this.config = {
@@ -59,18 +64,34 @@ export class AccessibilityManager {
   private createLiveRegion(): void {
     if (this.liveRegion) return
 
+    // Adopt an existing region instead of appending a duplicate: Turbo caches
+    // the <body> including JS-injected nodes, so a region created before a
+    // navigation is restored along with the snapshot.
+    const existingRegion = document.getElementById('live-region')
+    if (existingRegion) {
+      this.liveRegion = existingRegion
+      return
+    }
+
     this.liveRegion = document.createElement('div')
     this.liveRegion.id = 'live-region'
     this.liveRegion.className = 'live-region'
     this.liveRegion.setAttribute('aria-live', 'polite')
     this.liveRegion.setAttribute('aria-atomic', 'true')
     this.liveRegion.setAttribute('role', 'status')
-    
+
     document.body.append(this.liveRegion)
   }
 
   // WCAG 2.4.1: Bypass Blocks
   private addSkipLinks(): void {
+    // Same Turbo snapshot concern as createLiveRegion: skip links restored
+    // with a cached <body> must not be injected a second time.
+    if (document.querySelector('.skip-links')) {
+      this.ensureSkipTargets()
+      return
+    }
+
     const skipLinksContainer = document.createElement('div')
     skipLinksContainer.className = 'skip-links'
     
@@ -113,51 +134,22 @@ export class AccessibilityManager {
 
   // WCAG 2.4.3: Focus Order & 2.4.7: Focus Visible
   private initFocusManagement(): void {
+    // Note: focus must never be wrapped at the document edges — trapping Tab
+    // inside the page prevents keyboard users from reaching browser chrome
+    // and is itself a WCAG 2.1.2 (No Keyboard Trap) failure. Focus trapping
+    // is only legitimate inside active modal dialogs, which Bootstrap already
+    // handles.
     document.addEventListener('keydown', (event) => {
-      if (event.key === 'Tab') {
-        this.handleTabNavigation(event)
-      }
       if (event.key === 'Escape') {
         this.handleEscapeKey(event)
       }
-    })
+    }, { signal: this.signal })
 
     // Focus management for modals and dropdowns
     this.initModalFocusManagement()
     this.initDropdownFocusManagement()
   }
 
-  private handleTabNavigation(event: KeyboardEvent): void {
-    const focusableElements = this.getFocusableElements()
-    const currentIndex = focusableElements.indexOf(document.activeElement as HTMLElement)
-    
-    if (event.shiftKey) {
-      // Shift+Tab (backward)
-      if (currentIndex <= 0) {
-        event.preventDefault()
-        focusableElements.at(-1)?.focus()
-      }
-    } else if (currentIndex >= focusableElements.length - 1) {
-      // Tab (forward)
-      event.preventDefault()
-      focusableElements[0]?.focus()
-    }
-  }
-
-  private getFocusableElements(): HTMLElement[] {
-    const selector = [
-      'a[href]',
-      'button:not([disabled])',
-      'input:not([disabled])',
-      'select:not([disabled])',
-      'textarea:not([disabled])',
-      '[tabindex]:not([tabindex="-1"])',
-      '[contenteditable="true"]'
-    ].join(', ')
-
-    return Array.from(document.querySelectorAll(selector)) as HTMLElement[]
-  }
-
   private handleEscapeKey(event: KeyboardEvent): void {
     // Close dropdowns, but let Bootstrap handle its own modal keyboard behavior
     const activeModal = document.querySelector('.modal.show')
@@ -181,18 +173,24 @@ export class AccessibilityManager {
     // Add keyboard support for custom components
     document.addEventListener('keydown', (event) => {
       const target = event.target as HTMLElement
-      
+
+      // Never intercept keys inside editable controls: arrow keys must keep
+      // moving the caret in e.g. a navbar search input.
+      if (target.matches('input, textarea, select, [contenteditable], [contenteditable] *')) {
+        return
+      }
+
       // Handle arrow key navigation for menus
       if (target.closest('.nav, .navbar-nav, .dropdown-menu')) {
         this.handleMenuNavigation(event)
       }
-      
+
       // Handle Enter and Space for custom buttons
       if ((event.key === 'Enter' || event.key === ' ') && target.hasAttribute('role') && target.getAttribute('role') === 'button' && !target.matches('button, input[type="button"], input[type="submit"]')) {
         event.preventDefault()
         target.click()
       }
-    })
+    }, { signal: this.signal })
   }
 
   private handleMenuNavigation(event: KeyboardEvent): void {
@@ -201,9 +199,18 @@ export class AccessibilityManager {
     }
 
     const currentElement = event.target as HTMLElement
-    const menuItems = Array.from(currentElement.closest('.nav, .navbar-nav, .dropdown-menu')?.querySelectorAll('a, button') || []) as HTMLElement[]
+    const menuItems = (Array.from(currentElement.closest('.nav, .navbar-nav, .dropdown-menu')?.querySelectorAll('a, button') || []) as HTMLElement[])
+      // Skip items hidden inside collapsed submenus or closed dropdowns.
+      .filter(item => item.offsetParent !== null)
     const currentIndex = menuItems.indexOf(currentElement)
-    
+
+    // Only take over navigation when focus is actually on a menu item;
+    // otherwise stealing the arrow keys would yank focus out of unrelated
+    // controls that merely sit inside a nav container.
+    if (currentIndex === -1) {
+      return
+    }
+
     let nextIndex: number
     
     switch (event.key) {
@@ -244,16 +251,20 @@ export class AccessibilityManager {
       // Disable smooth scrolling
       document.documentElement.style.scrollBehavior = 'auto'
       
-      // Reduce animation duration
-      const style = document.createElement('style')
-      style.textContent = `
-        *, *::before, *::after {
-          animation-duration: 0.01ms !important;
-          animation-iteration-count: 1 !important;
-          transition-duration: 0.01ms !important;
-        }
-      `
-      document.head.append(style)
+      // Reduce animation duration. The <head> survives Turbo navigations, so
+      // only inject the override stylesheet once to avoid stacking duplicates.
+      if (!document.getElementById('adminlte-reduce-motion')) {
+        const style = document.createElement('style')
+        style.id = 'adminlte-reduce-motion'
+        style.textContent = `
+          *, *::before, *::after {
+            animation-duration: 0.01ms !important;
+            animation-iteration-count: 1 !important;
+            transition-duration: 0.01ms !important;
+          }
+        `
+        document.head.append(style)
+      }
     }
   }
 
@@ -283,6 +294,11 @@ export class AccessibilityManager {
       childList: true,
       subtree: true
     })
+
+    // Stop observing the old <body> before Turbo swaps in a new one.
+    this.signal.addEventListener('abort', () => {
+      observer.disconnect()
+    }, { once: true })
   }
 
   // WCAG 1.3.1: Info and Relationships
@@ -351,6 +367,14 @@ export class AccessibilityManager {
   }
 
   private handleFormError(input: HTMLInputElement): void {
+    // Inputs lacking both an id and a name would otherwise collide on a
+    // single "-error" id. Assign a stable generated id once and persist it on
+    // the element so repeated `invalid` events reuse the same error node
+    // instead of appending a new orphaned one each time.
+    if (!input.id && !input.name) {
+      input.id = accessibilityUtils.generateId('field')
+    }
+
     const errorId = `${input.id || input.name}-error`
     let errorElement = document.getElementById(errorId)
     
@@ -368,7 +392,14 @@ export class AccessibilityManager {
     }
     
     errorElement.textContent = input.validationMessage
-    input.setAttribute('aria-describedby', errorId)
+    // Append to any existing aria-describedby (e.g. help text) instead of
+    // clobbering it.
+    const describedBy = (input.getAttribute('aria-describedby') || '').split(/\s+/).filter(Boolean)
+    if (!describedBy.includes(errorId)) {
+      describedBy.push(errorId)
+    }
+
+    input.setAttribute('aria-describedby', describedBy.join(' '))
     input.classList.add('is-invalid')
     
     this.announce(`Error in ${input.labels?.[0]?.textContent || input.name}: ${input.validationMessage}`, 'assertive')
@@ -376,25 +407,33 @@ export class AccessibilityManager {
 
   // Modal focus management
   private initModalFocusManagement(): void {
+    // Capture the trigger on `show` — before Bootstrap (or the `shown`
+    // handler below) moves focus into the modal. Capturing on `shown` would
+    // store an element inside the modal itself, so closing it would "restore"
+    // focus to a now-hidden node and drop focus to <body>.
+    document.addEventListener('show.bs.modal', () => {
+      this.focusHistory.push(document.activeElement as HTMLElement)
+    }, { signal: this.signal })
+
     document.addEventListener('shown.bs.modal', (event) => {
       const modal = event.target as HTMLElement
-      const focusableElements = modal.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')
-      
-      if (focusableElements.length > 0) {
-        (focusableElements[0] as HTMLElement).focus()
-      }
-      
-      // Store previous focus
-      this.focusHistory.push(document.activeElement as HTMLElement)
-    })
+      // Respect an explicit [autofocus] before falling back to the first
+      // focusable control.
+      const autofocusElement = modal.querySelector('[autofocus]') as HTMLElement | null
+      const firstFocusable = autofocusElement ||
+        (modal.querySelector('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])') as HTMLElement | null)
+
+      firstFocusable?.focus()
+    }, { signal: this.signal })
 
     document.addEventListener('hidden.bs.modal', () => {
-      // Restore previous focus
+      // Restore previous focus, unless the trigger has since been removed
+      // from the document (e.g. a delete-confirmation modal removing its row).
       const previousElement = this.focusHistory.pop()
-      if (previousElement) {
+      if (previousElement?.isConnected) {
         previousElement.focus()
       }
-    })
+    }, { signal: this.signal })
   }
 
   // Dropdown focus management
@@ -407,7 +446,7 @@ export class AccessibilityManager {
       if (firstItem) {
         firstItem.focus()
       }
-    })
+    }, { signal: this.signal })
   }
 
   // Public API methods
@@ -460,7 +499,7 @@ export class AccessibilityManager {
           event.preventDefault()
         }
       }
-    })
+    }, { signal: this.signal })
   }
 
   public addLandmarks(): void {
@@ -470,7 +509,9 @@ export class AccessibilityManager {
       const appMain = document.querySelector('.app-main')
       if (appMain) {
         appMain.setAttribute('role', 'main')
-        appMain.id = 'main'
+        if (!appMain.id) {
+          appMain.id = 'main'
+        }
       }
     }
 
@@ -505,10 +546,29 @@ export const initAccessibility = (config?: Partial<AccessibilityConfig>): Access
   return new AccessibilityManager(config)
 }
 
+// Parse a CSS color into RGB channels. Supports rgb()/rgba() strings and
+// 3- or 6-digit hex notation; anything else falls back to black.
+const parseColorChannels = (color: string): number[] => {
+  const hexMatch = /^#([\da-f]{3}|[\da-f]{6})$/i.exec(color.trim())
+  if (hexMatch) {
+    let hex = hexMatch[1]
+    if (hex.length === 3) {
+      hex = [...hex].map(character => character + character).join('')
+    }
+
+    return [
+      Number.parseInt(hex.slice(0, 2), 16),
+      Number.parseInt(hex.slice(2, 4), 16),
+      Number.parseInt(hex.slice(4, 6), 16)
+    ]
+  }
+
+  return color.match(/\d+/g)?.map(Number) || [0, 0, 0]
+}
+
 // Utility function for luminance calculation
 const getLuminance = (color: string): number => {
-  const rgb = color.match(/\d+/g)?.map(Number) || [0, 0, 0]
-  const [r, g, b] = rgb.map(c => {
+  const [r, g, b] = parseColorChannels(color).map(c => {
     c = c / 255
     return c <= 0.039_28 ? c / 12.92 : (c + 0.055) ** 2.4 / (1.055 ** 2.4)
   })

package/src/ts/adminlte.ts

@@ -5,10 +5,11 @@ import Treeview from './treeview.js'
 import DirectChat from './direct-chat.js'
 import FullScreen from './fullscreen.js'
 import PushMenu from './push-menu.js'
+import ColorMode from './color-mode.js'
 import { initAccessibility } from './accessibility.js'
 
 /**
- * AdminLTE v4.0.0
+ * AdminLTE v4.1.0
  * Author: Colorlib
  * Website: AdminLTE.io <https://adminlte.io>
  * License: Open source - MIT <https://opensource.org/licenses/MIT>
@@ -38,5 +39,6 @@ export {
   DirectChat,
   FullScreen,
   PushMenu,
+  ColorMode,
   initAccessibility
 }

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 }