admin-lte 4.0.4 → 4.2.0

package/CHANGELOG.md

@@ -5,7 +5,47 @@ All notable changes to AdminLTE will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [4.2.0] - 2026-08-06
+
+### Added
+
+- **Advanced form pages:** `forms/advanced.html` demonstrates the recommended Tom Select and Flatpickr integrations (searchable single select, tag-style multi-select, option groups loaded on demand; date, date-time, range, and time pickers), and `forms/editors.html` demonstrates Quill 2 in both the snow (toolbar) and bubble (inline) themes. CDN assets are pinned to the versions recommended on the docs Integrations page and carry SRI hashes. Both pages are linked from the sidebar's Forms menu.
+- **Top-nav layout demo:** `layout/top-nav.html` — a sidebar-less page whose primary navigation lives in the app-header as a plain Bootstrap `navbar-expand-lg` (collapse toggler on mobile, no PushMenu). No new CSS was needed: without an `.app-sidebar` in the markup, the `app-wrapper` grid's `auto` sidebar column collapses to zero width on its own.
+- **Color mode: server-rendered themes, and an opt-out for applications with their own theming.** ColorMode now resolves the theme from the visitor's stored choice, then a theme the page declared itself in `<html data-bs-theme="light|dark">`, then the OS preference — so a theme rendered server-side from a cookie or a user record is no longer overwritten on load, and no longer lost the first time the OS preference changes. Applications that manage `data-bs-theme` themselves — including anyone using a custom Bootstrap theme name, which ColorMode cannot resolve — turn the module off entirely with `<html data-lte-color-mode="off">`: nothing is written on load, on a `[data-bs-theme-value]` toggle click, or when the OS preference changes, and the pre-paint snippet in `<head>` honours it too (#6084, reported by @cytech; #6093, thanks @dfsmania). The snippet now flags the values it resolves itself with `data-lte-theme-resolved`, so a computed theme is never mistaken for one the page declared.
+- **`initialize()` / `teardown()` lifecycle API for client-side rendered layouts:** frameworks that build the layout after `DOMContentLoaded` into a persistent `<body>` (GWT and similar widget toolkits) can call `adminlte.initialize()` once the layout is attached — it tears down the previous cycle's listeners and re-runs every plugin's initialisation against the current DOM, and is safe to call repeatedly (#6083, thanks @themarioga). `teardown()` is the inverse, for apps that unmount the layout. Re-initialisation was hardened along the way: the accessibility module's per-field `invalid` listeners no longer stack across cycles, an `initialize()` call made while the document is still loading no longer suppresses the initial `DOMContentLoaded` pass, and calling `initialize()` from inside a lifecycle callback no longer recurses.
+
+### Changed
+
+- **Dev dependencies refreshed to their latest releases**, including two majors: `eslint-plugin-astro` 2 → 3 and `eslint-plugin-unicorn` 72 → 73, whose new `single-line-block-comment-style` rule prompted converting four one-line banner comments in `src/ts/util/index.ts` to line comments. Also Astro 7.1.6, ESLint 10.8, typescript-eslint 8.66, Sass 1.102, Rollup 4.62.4, Terser 5.49.2, PostCSS 8.5.25, happy-dom 20.11.1, `@astrojs/mdx` 7.0.5, plus concurrently, fs-extra and globals. TypeScript stays on 6.0.3: 7.0 has shipped, but both `typescript-eslint` (peer `>=4.8.4 <6.1.0`) and `@astrojs/check` (peer `^5 || ^6`) still cap it, so installing it fails dependency resolution outright. Nothing in `dist/` changed as a result. Supersedes #6085–#6092.
+- Component docstrings corrected in `base-component.ts` and `push-menu.ts` (#6082, thanks @dfsmania), the `adminlte-docs.scss` banner is now version-synced by `npm version` along with the other source banners, and the README's screenshots were downscaled to WebP for faster cold-cache loads.
+
+### Fixed
+
+- **A sidebar rendered collapsed no longer springs open on load:** a page shipping `<body class="sidebar-collapse">` had that state overwritten by PushMenu's responsive pass during initialisation, so a deliberately collapsed sidebar expanded itself on wide screens. The responsive pass now runs only when the sidebar was not already collapsed in the markup (#6076, thanks @dfsmania).
+- **The Color Mode docs page ran two switchers at once:** `docs/color-mode.html` still carried the pre-4.1 inline toggler, which bound its own handlers to the same `[data-bs-theme-value]` buttons as the bundled module and persisted to a different `localStorage` key (`theme` instead of `lte-theme`). It has been removed — the page now uses the shipped ColorMode like every other page.
+
+## [4.1.0] - 2026-07-02
+
+### Added
+
+- **ESM bundle and TypeScript declarations on npm:** `dist/js/adminlte.esm.js` (+ `.min`) ships alongside the UMD build, generated `.d.ts` files ship under `dist/js/types/`, and package.json gains `module`, `types`, and a full `exports` map (with `sass`/`style` conditions and `./dist/*` + `./src/scss/*` subpaths). `import { PushMenu } from "admin-lte"` now resolves natively in Vite/webpack and type-checks out of the box — previously the package shipped a single minified UMD file with no typings at all.
+- **Component lifecycle API (Bootstrap-style):** every JS component now has `getInstance(element)`, `getOrCreateInstance(element, config?)` and `dispose()`, backed by a per-element WeakMap registry (instances are garbage-collected with their elements — Turbo-safe). The data API now uses **delegated document-level listeners**, so toggles inside content inserted after page load (AJAX partials, Turbo Frames) work without re-initialisation. `PushMenu` is finally controllable programmatically via `PushMenu.getInstance(sidebar)`.
+- **`ColorMode` module in the bundle:** the light/dark/auto switcher (persisted in `lte-theme`, OS-preference aware, `[data-bs-theme-value]` data-API, `changed.lte.color-mode` event) is now part of `adminlte.js`. Applications no longer need to copy the demo's inline script; the demo pages now use the bundled module. Only the tiny no-flash snippet in `<head>` remains inline, by design.
+- **`bootstrap` declared as a peer dependency** — the Sass source imports it, so `@use "admin-lte/src/scss/adminlte"` now works after a plain `npm install admin-lte` (npm installs the peer automatically). Documented the required Sass load-path setup.
+- **New demo pages:** a blank **starter page** (the most-requested v3 page, absent from v4), a dedicated **ApexCharts** page with six chart types, and a **Users** management page (searchable directory table, add-user and delete-confirmation modals, pagination). All linked from the sidebar.
+- **Test baseline:** a vitest + happy-dom unit suite (30 tests across the component lifecycle, card/treeview/push-menu behavior, ColorMode, and slide animations) wired into `npm run production`; plus `npm run test-a11y` — an axe-core check over key built demo pages that fails on serious/critical WCAG violations, with a dedicated GitHub workflow.
+
+### Fixed
+
+- First findings of the new axe gate, fixed at the source: breadcrumb links now use the darker link shade (Bootstrap's default blue was 4.26:1 against the content-header's gray background — below WCAG AA's 4.5:1), the direct-chat message pane is keyboard-focusable (`tabindex="0"` + `role="log"`), and muted footnote text uses `text-body-secondary` instead of the failing `text-secondary`.
+
+### Changed
+
+- **Component events overhauled (behavior change):** all plugin events are now bubbling `CustomEvent`s dispatched on the component's root element (the card, the nav item, the sidebar) — previously most were non-bubbling and card events fired on whatever was clicked, including the `<i>` icon. Animated actions gained cancelable "before" events (`collapse`/`expand`/`remove.lte.card-widget`, `expand`/`collapse.lte.treeview`, `open`/`collapse.lte.push-menu`) and their "after" events (`collapsed`, `expanded`, `removed`, `opened`, …) now fire when the animation completes, not when it starts. If you listened for card events on the tool buttons themselves, listen on the card or on `document` instead.
+- **Docs styles split out of the production CSS:** the documentation/FAQ styling now compiles to a separate `adminlte-docs.css`, loaded only by the docs pages. Together with the 4.0.4 dedup, `adminlte.min.css` is down to ~40.4 KB gzip (from 46.7 KB in 4.0.3); bundlewatch budgets tightened accordingly.
+- **Vendored Bootstrap variables fork replaced:** the 1,766-line `_bootstrap-variables.scss` copy (which had to be re-synced by hand every Bootstrap release) is gone; AdminLTE's ~10 actual changes now live in a small `_bootstrap-overrides.scss` loaded before Bootstrap's own variables. Compiled CSS is byte-identical.
+- **Sass deprecation policy:** the build no longer silences all warnings (`--quiet`); it silences only dependency warnings and the known `@import` deprecation (`--quiet-deps --silence-deprecation=import`), so new deprecations in AdminLTE's own code surface at build time. All deprecated global built-ins (`map-get`, `map-keys`) migrated to the `sass:map` module. The full `@use` module-system migration is intentionally deferred until Bootstrap ships module-system Sass (Bootstrap 6) — Bootstrap 5's partials are designed around `@import`'s shared global namespace and cannot be loaded individually via `@use`.
+- Rewrote the color-mode docs page around the bundled `ColorMode` module (the old copy-paste script it showed used a stale storage key); tsconfig.json no longer carries the invalid `"root": true` option.
 
 ## [4.0.4] - 2026-07-02
 

package/README.md

@@ -19,10 +19,10 @@ large desktops, and it's MIT-licensed.
 
 <p align="center">
   <a href="https://adminlte.io/themes/v4/">
-    <img alt="AdminLTE 4 dashboard — light mode" src=".github/assets/dashboard-light.png" width="49%">
+    <img alt="AdminLTE 4 dashboard — light mode" src=".github/assets/dashboard-light.webp" width="49%">
   </a>
   <a href="https://adminlte.io/themes/v4/">
-    <img alt="AdminLTE 4 dashboard — dark mode" src=".github/assets/dashboard-dark.png" width="49%">
+    <img alt="AdminLTE 4 dashboard — dark mode" src=".github/assets/dashboard-dark.webp" width="49%">
   </a>
 </p>
 
@@ -161,7 +161,7 @@ including editions built for the same stacks AdminLTE integrates with:
   <tr>
     <td align="center" width="50%">
       <a href="https://dashboardpack.com/theme-details/admindek-html/?utm_source=github&utm_medium=readme&utm_campaign=adminlte">
-        <img src=".github/assets/premium/admindek.png" alt="Admindek — feature-rich Bootstrap 5 dashboard with dark mode" width="100%">
+        <img src=".github/assets/premium/admindek.webp" alt="Admindek — feature-rich Bootstrap 5 dashboard with dark mode" width="100%">
       </a>
       <br>
       <a href="https://dashboardpack.com/theme-details/admindek-html/?utm_source=github&utm_medium=readme&utm_campaign=adminlte"><strong>Admindek</strong></a>
@@ -173,7 +173,7 @@ including editions built for the same stacks AdminLTE integrates with:
     </td>
     <td align="center" width="50%">
       <a href="https://dashboardpack.com/theme-details/apex-dashboard-nextjs/?utm_source=github&utm_medium=readme&utm_campaign=adminlte">
-        <img src=".github/assets/premium/apex.png" alt="Apex Dashboard — admin template available for Next.js, Laravel, Django and Angular" width="100%">
+        <img src=".github/assets/premium/apex.webp" alt="Apex Dashboard — admin template available for Next.js, Laravel, Django and Angular" width="100%">
       </a>
       <br>
       <a href="https://dashboardpack.com/theme-details/apex-dashboard-nextjs/?utm_source=github&utm_medium=readme&utm_campaign=adminlte"><strong>Apex Dashboard</strong></a>
@@ -188,7 +188,7 @@ including editions built for the same stacks AdminLTE integrates with:
   <tr>
     <td align="center" width="50%">
       <a href="https://dashboardpack.com/theme-details/zenith-dashboard-django/?utm_source=github&utm_medium=readme&utm_campaign=adminlte">
-        <img src=".github/assets/premium/zenith.png" alt="Zenith — ultra-minimal admin dashboard, Django edition" width="100%">
+        <img src=".github/assets/premium/zenith.webp" alt="Zenith — ultra-minimal admin dashboard, Django edition" width="100%">
       </a>
       <br>
       <a href="https://dashboardpack.com/theme-details/zenith-dashboard-django/?utm_source=github&utm_medium=readme&utm_campaign=adminlte"><strong>Zenith Dashboard — Django</strong></a>
@@ -197,7 +197,7 @@ including editions built for the same stacks AdminLTE integrates with:
     </td>
     <td align="center" width="50%">
       <a href="https://dashboardpack.com/theme-details/haze-dashboard-nuxt/?utm_source=github&utm_medium=readme&utm_campaign=adminlte">
-        <img src=".github/assets/premium/haze.png" alt="Haze — Nuxt 4 admin dashboard with 92+ pages and 5 dashboards" width="100%">
+        <img src=".github/assets/premium/haze.webp" alt="Haze — Nuxt 4 admin dashboard with 92+ pages and 5 dashboards" width="100%">
       </a>
       <br>
       <a href="https://dashboardpack.com/theme-details/haze-dashboard-nuxt/?utm_source=github&utm_medium=readme&utm_campaign=adminlte"><strong>Haze — Nuxt</strong></a>