admin-lte 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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).
 
+## [4.4.0] - 2026-08-18
+
+### Added
+
+- **Extended colour palette (`dist/css/adminlte-colors.css`)** — an opt-in stylesheet (≈ 5 kB gzipped; `adminlte.css` is unchanged) that adds fourteen colours — orange, amber, olive, teal, sky, indigo, violet, fuchsia, pink, and the chrome neutrals navy, steel, slate, graphite, midnight — as `--bs-*` tokens plus every family Bootstrap generates for its own theme colours: `.bg-*`, `.text-bg-*`, `.text-*`, `.border-*`, `.link-*`, `.bg-gradient-*` (also for the eight theme colours, as in v3), `.card-*` / `.card-outline`, `.callout-*`, `.direct-chat-*`, with the subtle/emphasis tokens for dark mode and a hover shade for `.btn.bg-*`. The palette is generated, not picked: in OKLCH, each chromatic colour is the lightest value whose white text still reaches 4.6:1 (WCAG AA), hues sit ≥ 17° from every Bootstrap theme colour and ≥ 20° from each other, chroma is capped at parity with `primary`, and the five neutrals are cool-tinted and sit at the lightness steps popular admin kits use for sidebars. `scripts/palette.mjs` regenerates it (`npm run palette`) and checks it (`--check`); a unit test keeps the Sass map and the demo data in step. Add your own with `$lte-palette-custom: ("brand": #hex)`, replace the set with `$lte-palette`, restore v3 names with `$lte-palette-aliases: ("lightblue": "sky", "maroon": "pink")`. Documented on the new **Colors** page (`docs/colors.html`) — palette, class families, 17 skin presets in four families (light, semi-dark, full dark, coloured & gradient) each with a layout thumbnail, widget-set presets, brand-colour recipe, design rules with a hue/chroma plot — and demonstrated on **UI → Colors** (`UI/colors.html`), which recolours its own sidebar and header live from thumbnail presets, shows the four dashboard sets and every component, and has a brand-colour checker that reports contrast, proposes a same-hue value that passes, and prints the Sass snippet (#6103, requested by @johnnyq).
+- **Header search and sidebar filter restyled** — one shared treatment (`mixins/_search-field.scss`): a quiet pill with the icon inside as the submit button, coloured only from theme-relative tokens (`--bs-emphasis-color-rgb`, `--bs-body-color`), so it reads as soft glass on any coloured or dark header / sidebar and soft grey on a white one, instead of a boxed `.input-group` with an outline button that turned near-black under `data-bs-theme="dark"`. The header field widens slightly on focus; below `md` an icon links to the search page. New variables `$lte-search-field-*` (width, focus width, font size, padding, icon space); the Main Header docs snippet, which still showed v3's inert `data-widget="navbar-search"`, now shows the real markup.
+- **Theme Customize (`generate/theme.html`)** offers the palette in its sidebar / navbar / footer pickers under "Extended palette", gained a preset row with the same thumbnails, reflects the page's current state on load, and defaults the colour mode to dark when a palette colour is picked; its three duplicated scripts are one controller.
+- The Migration and Customization pages point to the palette; the migration guide maps every AdminLTE 3 colour and skin class to its v4 form.
+
+### Fixed
+
+- **Sidebar taller than the viewport with the sidebar filter in place.** `.sidebar-wrapper` was sized with a hard-coded `100vh − header height`, which assumed only the brand sat above it; the `SidebarSearch` field added in 4.3.0 sits between the brand and the wrapper (on purpose, so it stays put while the menu scrolls), so the wrapper overflowed the sidebar by exactly the filter's height and the last menu items were cut off. `.app-sidebar` is now a flex column: brand and filter keep their size (`flex: 0 0 auto`), `.sidebar-wrapper` fills the rest (`flex: 1 1 auto; min-height: 0`) and scrolls — in fixed layouts, the `fixed-header`-only case, and the off-canvas sidebar. Anything else placed above or below the menu now sizes correctly too, without a height calc (#6104, reported by @dfsmania).
+
+## [4.3.1] - 2026-08-10
+
+### Fixed
+
+- **Ribbons left the card corner bare.** The banner was centred on its clipping square, but the square's centre is the point *furthest* from the corner — so the banner sat too far into the card, left a large empty triangle at the corner it is supposed to cover, and had its label cut off by the clip. The banner's centre now sits on the corner's bisector at ~46% of the square's side, the proportion that leaves the label room and fills the corner, and the width is the chord across the corner rather than the square's diagonal. RTL mirrors as before.
+- The ribbons demo uses short labels and states the constraint: the banner is clipped to the corner, so only about `64px` of it is readable at the default size. `.ribbon-lg` and `.ribbon-xl` give more room. Documented on the Miscellaneous components page.
+
+## [4.3.0] - 2026-08-10
+
+### Added
+
+- **Gallery page (`pages/gallery.html`)** — a filterable media library: responsive tile grid, per-item action menus, a live result count and an empty state. It carries **no image library at all** — the tiles are a Bootstrap `.ratio` box plus `.object-fit-cover`, and the category filter is ~25 lines of page-local script, so nothing is added to `adminlte.js` and no CDN dependency is imposed on anyone who just wants the grid. A lightbox stays deliberately out of scope; it is the part that needs a dependency.
+- **Search results page (`pages/search-results.html`)** — typed results (page / user / file / project, each with its own icon and badge) over a tabbed type filter, plus a refine panel, related searches, pagination and a worked "no results" state. The navbar search now posts to it with `name="q"` instead of `action="#"`, so the search added alongside `SidebarSearch` has a real destination.
+- **Language menu in the app header** — a `bi-translate` dropdown listing five locales with the current one marked via `.active` + `aria-current`, and `hreflang` on each item. It is markup only, by design; the new **"A language switcher wired to a real locale"** recipe in the docs covers the four things that separate a working switcher from set dressing — real per-locale links rather than `#` plus a click handler, the locale living in the URL or a cookie rather than `localStorage` (the server has to know it *before* it renders), marking the current language for assistive tech, and serving `adminlte.rtl.css` alongside `dir="rtl"` when switching to an RTL locale.
+- **`SidebarSearch` plugin** — a filter field above the sidebar menu (`data-lte-toggle="sidebar-search"` on an input, optional `data-lte-target` for the menu). Typing hides non-matching entries and expands whatever submenu holds a match; a group whose own name matches keeps its entire subtree, so expanding it is never a dead end. Clearing the field — `ESC`, the native clear button, or `clear()` — restores every entry *and* each submenu's previous open state, including the inline `display` Treeview's slide animation leaves behind. Entries are hidden with the `hidden` attribute rather than a class, so they leave the accessibility tree too. Fires `filtered.lte.sidebar-search` with `{ query, matches }`; both listeners are delegated on `document`, so a sidebar rendered after load needs no re-initialisation. Wired into every demo and docs page, and documented at `docs/javascript/sidebar-search.html`.
+- **Navbar search** in the app header — a `role="search"` form with a visually-hidden label, shown from the `md` breakpoint up, posting to the new search results page.
+- **Ribbons** (`.ribbon-wrapper` + `.ribbon`, sizes `.ribbon-lg` / `.ribbon-xl`) — the corner banner from v3, rebuilt. The wrapper clips the banner and the banner is centred on it before rotating, so the whole geometry follows one custom property (`--lte-ribbon-size`) and stays correct at every scale; the clip inherits the parent's corner radius, so it follows a rounded card instead of cutting a square out of it. Colour comes from a `.text-bg-*` utility and long labels truncate rather than breaking the shape. rtlcss mirrors both the corner and the rotation, so RTL needs no extra markup. New demo page at `UI/ribbons.html`.
+- **Social and post widgets** (`.user-block`, `.post`, `.widget-user`, `.widget-user-2`, `.description-block`) — the profile cards and activity-feed blocks from v3, keeping their v3 class names so migrating markup works unchanged, but laid out with grid and flex rather than floats and coloured with Bootstrap utilities. `.user-block` renders avatar, name and meta from flat markup with no wrapper element. New demo page at `widgets/social.html`.
+- **Nav tabs & pills, modal and offcanvas sections** on `UI/general.html` — the three Bootstrap components the components showcase did not yet cover.
+- **Card and Miscellaneous documentation pages** (`docs/components/card.html`, `docs/components/miscellaneous.html`) — between them they document every AdminLTE component that ships CSS but had no reference until now: cards (anatomy, colour variants, states, tabbed cards, Sass variables), callouts, ribbons, small box, info box, timeline, the social/post widgets, progress-bar sizes, themed toasts and the image-size utilities.
+- **Select2 compatibility theme (`dist/css/adminlte-select2.css`)** — an opt-in, **CSS-only** sheet for projects that can't drop Select2 yet. AdminLTE still bundles neither Select2 nor jQuery and nothing is added to `adminlte.css`; load this one extra stylesheet after `select2.css` and a Select2 you bring yourself inherits Bootstrap 5.3's form metrics (`.form-select-sm` / `-lg` on the original `<select>` are honoured), focus ring, `.is-invalid` / `.is-valid` states, input-group corner rounding, badge-style multi-select pills, and `data-bs-theme` dark mode — including the body-appended dropdown. It also raises the dropdown above `.modal`, which removes the usual need for `dropdownParent`. Source lives in `src/scss/compat/_select2.scss` for anyone compiling their own Sass; RTL and minified variants are generated alongside the rest of the CSS (#6097, requested by @saddam2512).
+- **Third-party plugin replacement table** on the Migration page: every jQuery widget AdminLTE 3 bundled (Select2, DataTables, Summernote, iCheck, bootstrap-datepicker, jQuery Knob, Mapael, …) mapped to its vanilla-JS successor. The old plugin names were absent from the v4 docs entirely, so anyone searching for the plugin they knew found nothing and concluded it was unsupported.
+- **Select2 → Tom Select API mapping**, on both the Advanced Elements demo page and the Integrations docs page: 19 options, methods and events translated one-to-one (`ajax` → `load` + `loadThrottle`, `templateResult` → `render.option`, `select2("destroy")` → `ts.destroy()`, and so on).
+- **jsVectorMap** documented on the Integrations page as the dependency-free successor to AdminLTE 3's jQuery Mapael.
+- **New FAQ entry, "Does AdminLTE 4 support Select2?"**, plus a pointer from the existing jQuery question to the replacement table. The Deployment asset table and the RTL page now list the optional Select2 sheet alongside the core builds, and the README's breaking-changes list links the replacement table.
+
+### Changed
+
+- **Removed the dead `src/html/components/docs/faq.mdx`.** The docs FAQ has been rendered from the typed `sections` array in `src/html/pages/docs/faq.astro` since the accordion rewrite, and nothing imported the `.mdx` any more — but two later commits kept editing it, so those edits silently did nothing. It is the only docs `.mdx` with no importer; every other one is rendered by its matching `pages/docs/*.astro`.
+- **The remote-data Tom Select demo in `forms/advanced.html` is now the real pattern**, not a `setTimeout` sketch: request debouncing via `loadThrottle`, in-flight cancellation via `AbortController`, and page-by-page loading through the `virtual_scroll` plugin against a 72-record stub whose `{ results, next }` response shape matches a real endpoint — swap the stub body for a single `fetch()` and it works unchanged. The single select also gained the `clear_button` plugin.
+- **The axe gate covers 16 pages** (from 10), adding `UI/general.html`, `UI/ribbons.html`, `widgets/social.html`, `pages/gallery.html`, `pages/search-results.html` and `docs/components/miscellaneous.html`. Unit tests are up to 62 (from 51). The two new pages needed three Bootstrap-default contrast fixes the gate caught: `.text-secondary` under 4.5:1 on the tertiary page ground, the nav-tab link blue under it on the same ground (the tabs moved onto the card surface, which is the documented `.card-tabs` shape), and `.btn-outline-secondary` under it on a card footer.
+- **Outline buttons on `UI/general.html` are demonstrated where they are legible.** The warning, info and light outline variants draw their text in a light colour that falls below 4.5:1 on a light surface — adding the page to the axe gate surfaced it. They now sit on a dark panel, with a note saying why, which is also the guidance Bootstrap gives for them.
+- **Bundlewatch budgets raised** for the ribbon, widget and SidebarSearch additions: `adminlte.min.css` 42.5 → 43.5 kB and `adminlte.min.js` 7.5 → 8.5 kB gzip (and the matching RTL/ESM/unminified entries).
+
+### Fixed
+
+- **Dashboard v2 linked to a page that does not exist.** Seven order-number links in `index2.html` pointed at `pages/examples/invoice.html`; the invoice page is at `pages/invoice.html`. Caught by a new link-resolution pass over every built page.
+- **`#navigation` no longer resolves to the app header.** `ensureSkipTargets()` looked its two skip-link targets up with a single selector list each (`#navigation, nav, [role="navigation"]`), but a selector list resolves in *document order* rather than by which selector matched — so on every demo page, where the header `<nav>` precedes the sidebar menu that already carries `id="navigation"`, the header was stamped with the id a second time. That left a duplicate id in the document, pointed the "Skip to navigation" link at the header instead of the menu, and silently redirected any application code doing `document.querySelector("#navigation")` to the wrong element. An element the page already gave the id to now always wins.
+
 ## [4.2.0] - 2026-08-06
 
 ### Added

package/README.md

@@ -113,6 +113,21 @@ The v4 line is a ground-up rewrite on Bootstrap 5.3 with **no jQuery**: 18 new d
 a documentation overhaul, and major dependency upgrades. See the
 [CHANGELOG](CHANGELOG.md) for full details.
 
+### New in 4.3
+
+- **Sidebar search** — a new `SidebarSearch` plugin filters the menu as you type, expanding
+  whatever submenu holds a match and restoring the menu exactly as it was when cleared.
+  Paired with a navbar search in the app header.
+- **Ribbons** — corner banners (`.ribbon-wrapper` + `.ribbon`) in three sizes, mirrored
+  automatically in RTL, with the clip following the card's corner radius.
+- **Social & post widgets** — `.user-block`, `.post`, `.widget-user`, `.widget-user-2` and
+  `.description-block`, laid out with grid and flex.
+- **Three new demo pages** — Gallery (filterable media library, no image library required),
+  Search Results (typed results with a refine panel), and Ribbons.
+- **Nav tabs, modals and offcanvas** added to the General UI Elements showcase.
+- **Card and Miscellaneous docs pages**, plus a language switcher recipe — every component
+  that ships CSS now has a reference page.
+
 <details>
 <summary>Highlights</summary>
 
@@ -128,7 +143,7 @@ a documentation overhaul, and major dependency upgrades. See the
 
 - New pages: Getting Started, Customization & Theming, RTL Support, Migration from v3, Layout Blueprint, Recipes, Deployment & Performance, Recommended Integrations, JavaScript Plugins Overview
 - Rewritten Introduction with four labelled install paths (CDN / npm / source / Composer)
-- FAQ rebuilt with hero, live search, section chips, and an accordion of 19 questions
+- FAQ rebuilt with hero, live search, section chips, and an accordion of 23 questions
 - Split sidebar navigation: dashboard demo and docs each have their own nav
 
 **Major dependency upgrades**
@@ -145,6 +160,8 @@ a documentation overhaul, and major dependency upgrades. See the
 - Data attributes: `data-toggle` → `data-bs-toggle`, `data-widget="pushmenu"` → `data-lte-toggle="sidebar"`, `data-widget="treeview"` → `data-lte-toggle="treeview"`
 - Dark mode: `.dark-mode` body class → `data-bs-theme="dark"` attribute (Bootstrap 5.3 native)
 - jQuery no longer required; plugins are vanilla TypeScript
+- The bundled `plugins/` folder is gone — every v3 jQuery widget has a documented vanilla-JS successor ([replacement table](https://adminlte.io/themes/v4/docs/migration.html#third-party-plugin-replacements): Select2 → Tom Select, DataTables → Tabulator, Summernote → Quill, …)
+- The v3 extra colours (`.bg-navy`, `.bg-teal`, the sidebar skins, …) live in an opt-in stylesheet, `dist/css/adminlte-colors.css` — fourteen redesigned colours, every one readable with white text, 17 skin presets, plus a one-line hook for your brand colour ([Colors docs](https://adminlte.io/themes/v4/docs/colors.html), [live demo](https://adminlte.io/themes/v4/UI/colors.html)). Nothing is added to `adminlte.css`.
 
 See the dedicated [Migration from v3](https://adminlte.io/themes/v4/docs/migration.html) guide.