admin-lte 4.0.0-rc6 → 4.0.0

package/src/ts/push-menu.ts

@@ -1,9 +1,9 @@
 /**
- * --------------------------------------------
+ * ----------------------------------------------------------------------------
  * @file AdminLTE push-menu.ts
  * @description Push menu for AdminLTE.
  * @license MIT
- * --------------------------------------------
+ * ----------------------------------------------------------------------------
  */
 
 import {
@@ -11,34 +11,44 @@ import {
 } from './util/index'
 
 /**
- * ------------------------------------------------------------------------
+ * ----------------------------------------------------------------------------
  * Constants
- * ------------------------------------------------------------------------
+ * ----------------------------------------------------------------------------
  */
 
 const DATA_KEY = 'lte.push-menu'
 const EVENT_KEY = `.${DATA_KEY}`
-
 const EVENT_OPEN = `open${EVENT_KEY}`
 const EVENT_COLLAPSE = `collapse${EVENT_KEY}`
 
 const CLASS_NAME_SIDEBAR_MINI = 'sidebar-mini'
-const CLASS_NAME_SIDEBAR_COLLAPSE = 'sidebar-collapse'
-const CLASS_NAME_SIDEBAR_OPEN = 'sidebar-open'
 const CLASS_NAME_SIDEBAR_EXPAND = 'sidebar-expand'
 const CLASS_NAME_SIDEBAR_OVERLAY = 'sidebar-overlay'
-const CLASS_NAME_MENU_OPEN = 'menu-open'
+
+// Classes used to explicitly indicate the sidebar state.
+// - sidebar-collapse: Indicates the sidebar is explicitly collapsed.
+// - sidebar-open: Indicates the sidebar is explicitly open on mobile sizes.
+const CLASS_NAME_SIDEBAR_COLLAPSE = 'sidebar-collapse'
+const CLASS_NAME_SIDEBAR_OPEN = 'sidebar-open'
 
 const SELECTOR_APP_SIDEBAR = '.app-sidebar'
-const SELECTOR_SIDEBAR_MENU = '.sidebar-menu'
-const SELECTOR_NAV_ITEM = '.nav-item'
-const SELECTOR_NAV_TREEVIEW = '.nav-treeview'
 const SELECTOR_APP_WRAPPER = '.app-wrapper'
 const SELECTOR_SIDEBAR_EXPAND = `[class*="${CLASS_NAME_SIDEBAR_EXPAND}"]`
 const SELECTOR_SIDEBAR_TOGGLE = '[data-lte-toggle="sidebar"]'
 
 const STORAGE_KEY_SIDEBAR_STATE = 'lte.sidebar.state'
 
+/**
+ * ----------------------------------------------------------------------------
+ * Configuration Object Interface
+ * - sidebarBreakpoint: The screen width (in pixels) below which the sidebar
+ *   is considered to be on a "mobile" size and should be collapsed by default
+ *   unless explicitly opened.
+ * - enablePersistence: Whether to save the sidebar state (collapsed/open) in
+ *   localStorage and restore it on page load.
+ * ----------------------------------------------------------------------------
+ */
+
 type Config = {
   sidebarBreakpoint: number;
   enablePersistence: boolean;
@@ -46,12 +56,13 @@ type Config = {
 
 const Defaults: Config = {
   sidebarBreakpoint: 992,
-  enablePersistence: true
+  enablePersistence: false
 }
 
 /**
+ * ----------------------------------------------------------------------------
  * Class Definition
- * ====================================================
+ * ----------------------------------------------------------------------------
  */
 
 class PushMenu {
@@ -63,120 +74,191 @@ class PushMenu {
     this._config = { ...Defaults, ...config }
   }
 
-  menusClose() {
-    const navTreeview = document.querySelectorAll<HTMLElement>(SELECTOR_NAV_TREEVIEW)
+  /**
+   * Check if the sidebar is collapsed.
+   *
+   * @returns True if the sidebar is collapsed, false otherwise.
+   */
+  isCollapsed(): boolean {
+    return document.body.classList.contains(CLASS_NAME_SIDEBAR_COLLAPSE)
+  }
 
-    navTreeview.forEach(navTree => {
-      navTree.style.removeProperty('display')
-      navTree.style.removeProperty('height')
-    })
+  /**
+   * Check if the sidebar is explicitly open on mobile sizes.
+   *
+   * @returns True if the sidebar is explicitly open, false otherwise.
+   */
+  isExplicitlyOpen(): boolean {
+    return document.body.classList.contains(CLASS_NAME_SIDEBAR_OPEN)
+  }
 
-    const navSidebar = document.querySelector(SELECTOR_SIDEBAR_MENU)
-    const navItem = navSidebar?.querySelectorAll(SELECTOR_NAV_ITEM)
+  /**
+   * Check if the sidebar is in mini mode.
+   *
+   * @returns True if the sidebar is in mini mode, false otherwise.
+   */
+  isMiniMode(): boolean {
+    return document.body.classList.contains(CLASS_NAME_SIDEBAR_MINI)
+  }
 
-    if (navItem) {
-      navItem.forEach(navI => {
-        navI.classList.remove(CLASS_NAME_MENU_OPEN)
-      })
-    }
+  /**
+   * Check if the current screen size is considered "mobile" based on the
+   * sidebarBreakpoint config value.
+   *
+   * @returns True if the screen size is mobile, false otherwise.
+   */
+  isMobileSize(): boolean {
+    return globalThis.innerWidth <= this._config.sidebarBreakpoint
   }
 
-  expand() {
-    const event = new Event(EVENT_OPEN)
+  /**
+   * Expand the sidebar menu.
+   */
+  expand(): void {
+    // Remove the sidebar-collapse class. Only on mobile, add the sidebar-open
+    // class to indicate the sidebar is explicitly open.
 
     document.body.classList.remove(CLASS_NAME_SIDEBAR_COLLAPSE)
-    document.body.classList.add(CLASS_NAME_SIDEBAR_OPEN)
 
-    this._element.dispatchEvent(event)
+    if (this.isMobileSize()) {
+      document.body.classList.add(CLASS_NAME_SIDEBAR_OPEN)
+    }
+
+    // Dispatch the expand event.
+
+    this._element.dispatchEvent(new Event(EVENT_OPEN))
   }
 
-  collapse() {
-    const event = new Event(EVENT_COLLAPSE)
+  /**
+   * Collapse the sidebar menu.
+   */
+  collapse(): void {
+    // 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)
 
-    this._element.dispatchEvent(event)
+    // Dispatch the collapse event.
+
+    this._element.dispatchEvent(new Event(EVENT_COLLAPSE))
   }
 
-  addSidebarBreakPoint() {
-    const sidebarExpandList = document.querySelector(SELECTOR_SIDEBAR_EXPAND)?.classList ?? []
-    const sidebarExpand = Array.from(sidebarExpandList).find(className => className.startsWith(CLASS_NAME_SIDEBAR_EXPAND)) ?? ''
-    const sidebar = document.getElementsByClassName(sidebarExpand)[0]
-    const sidebarContent = globalThis.getComputedStyle(sidebar, '::before').getPropertyValue('content')
-    this._config = { ...this._config, sidebarBreakpoint: Number(sidebarContent.replace(/[^\d.-]/g, '')) }
-
-    // FIXED: Don't auto-collapse on mobile if sidebar is currently open
-    // This prevents resize events (triggered by scrolling) from closing the sidebar
-    const isCurrentlyOpen = document.body.classList.contains(CLASS_NAME_SIDEBAR_OPEN)
-    
-    if (window.innerWidth <= this._config.sidebarBreakpoint) {
-      // Only collapse if not currently open (prevents scroll-triggered closes)
-      if (!isCurrentlyOpen) {
-        this.collapse()
-      }
-    } else {
-      if (!document.body.classList.contains(CLASS_NAME_SIDEBAR_MINI)) {
-        this.expand()
-      }
+  /**
+   * Toggle the sidebar menu state.
+   */
+  toggle(): void {
+    // Toggle the sidebar state.
 
-      if (document.body.classList.contains(CLASS_NAME_SIDEBAR_MINI) && document.body.classList.contains(CLASS_NAME_SIDEBAR_COLLAPSE)) {
-        this.collapse()
-      }
-    }
-  }
+    const isCollapsed = this.isCollapsed()
 
-  toggle() {
-    if (document.body.classList.contains(CLASS_NAME_SIDEBAR_COLLAPSE)) {
+    if (isCollapsed) {
       this.expand()
     } else {
       this.collapse()
     }
 
-    this.saveSidebarState()
+    // If persistence is enabled, save the new state to localStorage.
+
+    if (this._config.enablePersistence) {
+      this.saveSidebarState(
+        isCollapsed ? CLASS_NAME_SIDEBAR_OPEN : CLASS_NAME_SIDEBAR_COLLAPSE
+      )
+    }
   }
 
   /**
-   * Save sidebar state to localStorage
+   * Read the CSS breakpoint of the sidebar from the DOM and update the
+   * sidebarBreakpoint config. This breakpoint is defined using a CSS ::before
+   * pseudo element on the sidebar-expand element when @media queries are used
+   * to change the sidebar behavior based on screen size.
    */
-  saveSidebarState(): void {
-    if (!this._config.enablePersistence) {
+  setupSidebarBreakPoint(): void {
+    // Find the sidebar-expand element in the DOM.
+
+    const sidebarExpand = document.querySelector(SELECTOR_SIDEBAR_EXPAND)
+
+    if (!sidebarExpand) {
+      return
+    }
+
+    // Read the content property of the ::before pseudo element to get the
+    // breakpoint value.
+
+    const content = globalThis.getComputedStyle(sidebarExpand, '::before')
+      .getPropertyValue('content')
+
+    // Update the config.sidebarBreakpoint value by extracting the numeric
+    // value from the content string.
+
+    if (!content || content === 'none') {
       return
     }
 
-    // Check for SSR environment
-    if (globalThis.window === undefined || globalThis.localStorage === undefined) {
+    const breakpointValue = Number(content.replace(/[^\d.-]/g, ''))
+
+    if (Number.isNaN(breakpointValue)) {
       return
     }
 
+    this._config = { ...this._config, sidebarBreakpoint: breakpointValue }
+  }
+
+  /**
+   * Update the sidebar state based on the current screen size and the
+   * sidebarBreakpoint config value.
+   */
+  updateStateByResponsiveLogic(): void {
+    if (this.isMobileSize()) {
+      // On mobile sizes, keep the sidebar collapsed unless explicitly opened
+      // by the user to prevent unintended collapse on scroll or resize events.
+
+      if (!this.isExplicitlyOpen()) {
+        this.collapse()
+      }
+    } else {
+      // On big screen sizes, keep the sidebar expanded unless in mini mode and
+      // explicitly collapsed.
+
+      if (!(this.isMiniMode() && this.isCollapsed())) {
+        this.expand()
+      }
+    }
+  }
+
+  /**
+   * Save sidebar state to localStorage.
+   *
+   * @param state The state to save ('sidebar-open' or 'sidebar-collapse').
+   */
+  saveSidebarState(state: string): void {
+    // Check for localStorage availability (not a SSR environment).
+
+    if (globalThis.localStorage === undefined) {
+      return
+    }
+
+    // Save the sidebar state to local storage.
+
     try {
-      const state = document.body.classList.contains(CLASS_NAME_SIDEBAR_COLLAPSE) ?
-        CLASS_NAME_SIDEBAR_COLLAPSE :
-        CLASS_NAME_SIDEBAR_OPEN
       localStorage.setItem(STORAGE_KEY_SIDEBAR_STATE, state)
     } catch {
-      // localStorage may be unavailable (private browsing, quota exceeded, etc.)
+      // The localStorage may be unavailable (private browsing, quota exceeded,
+      // etc.). Fail silently in these cases.
     }
   }
 
   /**
-   * Load sidebar state from localStorage
-   * Only applies on desktop; mobile always starts collapsed
+   * Load sidebar state from localStorage.
    */
   loadSidebarState(): void {
-    if (!this._config.enablePersistence) {
-      return
-    }
+    // Check for localStorage availability (not a SSR environment).
 
-    // Check for SSR environment
-    if (globalThis.window === undefined || globalThis.localStorage === undefined) {
+    if (globalThis.localStorage === undefined) {
       return
     }
 
-    // Don't restore state on mobile - let responsive behavior handle it
-    if (globalThis.innerWidth <= this._config.sidebarBreakpoint) {
-      return
-    }
+    // Load the sidebar state from local storage.
 
     try {
       const storedState = localStorage.getItem(STORAGE_KEY_SIDEBAR_STATE)
@@ -185,44 +267,118 @@ class PushMenu {
         this.collapse()
       } else if (storedState === CLASS_NAME_SIDEBAR_OPEN) {
         this.expand()
+      } else {
+        // If null (never saved), let the responsive logic apply.
+        this.updateStateByResponsiveLogic()
       }
-      // If null (never saved), let default behavior apply
     } catch {
-      // localStorage may be unavailable
+      // The localStorage may be unavailable. Let the responsive logic apply.
+      this.updateStateByResponsiveLogic()
+    }
+  }
+
+  /**
+   * Clear sidebar state from localStorage.
+   */
+  clearSidebarState(): void {
+    // Check for localStorage availability (not a SSR environment).
+
+    if (globalThis.localStorage === undefined) {
+      return
+    }
+
+    // Clear the sidebar state from local storage.
+
+    try {
+      localStorage.removeItem(STORAGE_KEY_SIDEBAR_STATE)
+    } catch {
+      // The localStorage may be unavailable. Fail silently in these cases.
     }
   }
 
-  init() {
-    this.addSidebarBreakPoint()
-    this.loadSidebarState()
+  /**
+   * Initialize the push menu plugin and setup the initial sidebar state.
+   */
+  init(): void {
+    // Read and setup the sidebar breakpoint from the DOM. This breakpoint is
+    // used to determine when the sidebar should be considered "mobile" vs
+    // "desktop".
+
+    this.setupSidebarBreakPoint()
+
+    // When persistence is not enabled, clear any saved state, just for safety.
+
+    if (!this._config.enablePersistence) {
+      this.clearSidebarState()
+    }
+
+    // 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.
+
+    if (this._config.enablePersistence && !this.isMobileSize()) {
+      this.loadSidebarState()
+    } else {
+      this.updateStateByResponsiveLogic()
+    }
   }
 }
 
 /**
- * ------------------------------------------------------------------------
+ * ----------------------------------------------------------------------------
  * Data Api implementation
- * ------------------------------------------------------------------------
+ * ----------------------------------------------------------------------------
  */
 
 onDOMContentLoaded(() => {
+  // Find the sidebar element in the DOM.
+
   const sidebar = document?.querySelector(SELECTOR_APP_SIDEBAR) as HTMLElement | undefined
 
-  if (sidebar) {
-    const data = new PushMenu(sidebar, Defaults)
-    data.init()
+  if (!sidebar) {
+    return
+  }
 
-    window.addEventListener('resize', () => {
-      data.init()
-    })
+  // Read config from data attributes on the sidebar element, falling back to
+  // Defaults if not present.
+
+  const sidebarBreakpointAttr = sidebar.dataset.sidebarBreakpoint
+  const enablePersistenceAttr = sidebar.dataset.enablePersistence
+
+  const config: Config = {
+    sidebarBreakpoint: sidebarBreakpointAttr === undefined ?
+      Defaults.sidebarBreakpoint :
+      Number(sidebarBreakpointAttr),
+    enablePersistence: enablePersistenceAttr === undefined ?
+      Defaults.enablePersistence :
+      enablePersistenceAttr === 'true'
   }
 
+  // Initialize the PushMenu plugin (a unique instance).
+
+  const pushMenu = new PushMenu(sidebar, config)
+  pushMenu.init()
+
+  // Update the sidebar state on window resize events.
+
+  window.addEventListener('resize', () => {
+    pushMenu.setupSidebarBreakPoint()
+    pushMenu.updateStateByResponsiveLogic()
+  })
+
+  // Create the sidebar overlay element and append it to the app wrapper.
+
   const sidebarOverlay = document.createElement('div')
   sidebarOverlay.className = CLASS_NAME_SIDEBAR_OVERLAY
   document.querySelector(SELECTOR_APP_WRAPPER)?.append(sidebarOverlay)
 
+  // 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.
+
   let overlayTouchMoved = false
 
-  // Handle touch events on overlay (area outside sidebar)
   sidebarOverlay.addEventListener('touchstart', () => {
     overlayTouchMoved = false
   }, { passive: true })
@@ -234,21 +390,19 @@ onDOMContentLoaded(() => {
   sidebarOverlay.addEventListener('touchend', event => {
     if (!overlayTouchMoved) {
       event.preventDefault()
-      const target = event.currentTarget as HTMLElement
-      const data = new PushMenu(target, Defaults)
-      data.collapse()
+      pushMenu.collapse()
     }
+
     overlayTouchMoved = false
   }, { passive: false })
 
-
   sidebarOverlay.addEventListener('click', event => {
     event.preventDefault()
-    const target = event.currentTarget as HTMLElement
-    const data = new PushMenu(target, Defaults)
-    data.collapse()
+    pushMenu.collapse()
   })
 
+  // Handle click events on sidebar toggle buttons.
+
   const fullBtn = document.querySelectorAll(SELECTOR_SIDEBAR_TOGGLE)
 
   fullBtn.forEach(btn => {
@@ -263,8 +417,7 @@ onDOMContentLoaded(() => {
 
       if (button) {
         event?.preventDefault()
-        const data = new PushMenu(button, Defaults)
-        data.toggle()
+        pushMenu.toggle()
       }
     })
   })

package/src/ts/util/index.ts

@@ -48,6 +48,11 @@ const safePropertyAccess = (obj: Record<string, unknown>, property: string): unk
 
 /* SLIDE UP */
 const slideUp = (target: HTMLElement, duration = 500) => {
+  if (duration <= 1) {
+    target.style.display = 'none'
+    return
+  }
+
   target.style.transitionProperty = 'height, margin, padding'
   target.style.transitionDuration = `${duration}ms`
   target.style.boxSizing = 'border-box'
@@ -85,6 +90,11 @@ const slideDown = (target: HTMLElement, duration = 500) => {
   }
 
   target.style.display = display
+
+  if (duration <= 1) {
+    return
+  }
+
   const height = target.offsetHeight
   target.style.overflow = 'hidden'
   target.style.height = '0'

package/.claude/settings.local.json

@@ -1,33 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm audit:*)",
-      "Bash(npm run build:*)",
-      "Bash(npm ls:*)",
-      "Bash(gh pr list:*)",
-      "Bash(npm outdated:*)",
-      "Bash(npm install:*)",
-      "Bash(gh pr view:*)",
-      "Bash(gh pr diff:*)",
-      "Bash(rm:*)",
-      "Bash(gh api:*)",
-      "Bash(gh issue list:*)",
-      "Bash(gh issue view:*)",
-      "Bash(npm run css:*)",
-      "Bash(npm run js:*)",
-      "Bash(npm run js-lint:*)",
-      "Bash(npm run css-lint:*)",
-      "Bash(npm run lint:*)",
-      "Bash(npm whoami:*)",
-      "Bash(npm run production:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(npm view:*)",
-      "Bash(cat:*)",
-      "Bash(npm pack:*)",
-      "Bash(npm publish:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}

package/CLAUDE.md

@@ -1,79 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-AdminLTE is a Bootstrap 5 admin dashboard template (v4.0.0-rc5). It provides responsive UI components for building admin panels and control dashboards.
-
-## Build Commands
-
-```bash
-npm install          # Install dependencies
-npm start            # Start dev server with file watching (http://localhost:3000)
-npm run build        # Build all assets (CSS, JS, docs)
-npm run production   # Full production build with linting and bundlewatch
-npm run lint         # Run all linters (JS, CSS, docs, lockfile)
-```
-
-### Individual Build Tasks
-
-```bash
-npm run css          # Build CSS only (compile, prefix, rtl, minify)
-npm run js           # Build JavaScript only (compile, minify)
-npm run css-lint     # Lint SCSS files
-npm run js-lint      # Lint TypeScript/JavaScript files
-```
-
-## Architecture
-
-### Source Structure
-
-- **src/ts/** - TypeScript source files compiled via Rollup to `dist/js/adminlte.js`
-- **src/scss/** - SCSS source files compiled via Sass to `dist/css/adminlte.css`
-- **src/html/** - Astro-based documentation/demo pages
-- **src/config/** - Build tool configurations (rollup, postcss, astro, assets)
-- **src/assets/** - Static images copied to dist
-
-### JavaScript Components (src/ts/)
-
-Entry point: `adminlte.ts` exports all components:
-- `Layout` - Core layout management and hold-transition behavior
-- `PushMenu` - Sidebar toggle functionality
-- `Treeview` - Hierarchical menu navigation
-- `CardWidget` - Card collapse/expand/remove actions
-- `DirectChat` - Chat widget toggle
-- `FullScreen` - Fullscreen toggle functionality
-- `initAccessibility` - WCAG 2.1 AA accessibility features
-
-### SCSS Structure (src/scss/)
-
-Entry point: `adminlte.scss` imports Bootstrap then AdminLTE components:
-- `_bootstrap-variables.scss` - Bootstrap variable overrides
-- `_variables.scss` / `_variables-dark.scss` - AdminLTE theme variables
-- `parts/` - Organized component groups (core, components, extra-components, pages, miscellaneous)
-- Individual component files (`_cards.scss`, `_app-sidebar.scss`, etc.)
-
-### Documentation (src/html/)
-
-Built with Astro framework:
-- `pages/` - Demo pages and documentation
-- `components/` - Reusable Astro components and MDX content
-- Output goes to `dist/html/` then flattened to `dist/`
-
-### Build Output (dist/)
-
-Production assets:
-- `dist/js/adminlte.min.js` - Compiled and minified JavaScript (UMD format)
-- `dist/css/adminlte.min.css` - Compiled and minified CSS
-- `dist/css/*.rtl.css` - RTL (right-to-left) variants
-- `dist/assets/` - Static assets
-
-## Key Technologies
-
-- Bootstrap 5.3.x - CSS framework base
-- TypeScript - JavaScript source language
-- Sass - CSS preprocessor
-- Rollup - JavaScript bundler
-- Astro - Documentation site generator
-- PostCSS with Autoprefixer and RTLCSS - CSS post-processing