active_admin_prism 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 856ce99225e35f41d012115c829406cb1de886ef7d36af3aa5b9e12978afe057
-  data.tar.gz: f7698fb938f3ea46bb86496ce3f80cc7cfaa74fd887a9425b8b46b7711f38a13
+  metadata.gz: 72cc73689e83be856fdc1e2e321df486dc8cb6033bcca1380aae1d7aed8a15b0
+  data.tar.gz: 999e31015012d3dcb58de142de2fe050754fba7903612f259f8ab92709388c05
 SHA512:
-  metadata.gz: add5ff5ce0bae255af731412b88af58dad8f9572323acf09f58ed8830253b44e13f269418a83ee796a50f0f19411ba7ea692893215e683379abd55acda003b9c
-  data.tar.gz: 4f4554adf93c92eb6cc090b7b7116b54bad8fdab489dfa84d59c5aded4f3282a40c2d864b6b01011d78dd786178a2d27042fc260eb73aa68f37917a9c91cc10c
+  metadata.gz: f94ead774c60a6c285fa59c624c0f472cd7eb31c2a21d970a7609a74bb3f948d86754d32050d416c7fdfc2fb9fdaa915c3071f998a7832dacb02027ecc606052
+  data.tar.gz: b71bbf23aceebcf5febdc7690b4b27064d4d1b9dfe050254e931b15060398a35b55ea0a228220386098fd061e57633ab7e1d00ec3bc5af350db520bfdbb2f23f

data/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## 0.1.3
+
+- A hamburger icon button next to the brand, at the top of the Prism
+  sidebar (`config.sidebar_collapsible`, default `true`), collapses it to
+  a narrow icon-only rail on desktop, expanding back to full width (with
+  labels) on another click — state persists across page loads. Purely a
+  desktop feature; the existing off-canvas mobile toggle below 900px is
+  unaffected either way. Every nav item keeps a native tooltip (its label,
+  on hover) so it stays identifiable while collapsed. Set
+  `config.sidebar_collapsible = false` to render no toggle at all — the
+  sidebar is always full width, matching this gem's behavior before this
+  flag existed.
+- Flash messages now render as floating toast cards (icon + message +
+  dismiss button + a countdown progress bar), pinned to the top-right
+  corner of the viewport and stacking if more than one is active, instead
+  of ActiveAdmin's plain inline banner. A type-colored icon
+  (`:check_circle`/`:alert_triangle`/`:alert_circle`/`:info`) is selected
+  from the flash's key — `:notice`/`:success`, `:alert`/`:warning`,
+  `:error`, and anything else, respectively. While `flash_auto_dismiss`
+  is on, a bar along the card's bottom edge visually counts down over
+  `flash_auto_dismiss_seconds`; hovering the card pauses both that bar
+  and the actual removal timer in lockstep (not just the animation), so a
+  flash a visitor is mid-read can't vanish out from under them. This
+  applies identically to Devise's sign-in/password/etc pages, which
+  needed a small layout override of their own — see
+  `app/views/layouts/active_admin_logged_out.html.erb` — since those
+  route through a completely separate layout ActiveAdmin itself ships
+  rather than through this gem's usual Arbre-based override point.
+- The active filters bar is now itself a shortcut to the Filters form —
+  clicking anywhere on it opens the (possibly collapsed) Filters panel and
+  scrolls it into view, instead of only the separate funnel icon doing
+  that.
+- Fixed: the active filters bar fell 12px short of the table's own right
+  edge instead of aligning flush with it — `.table_tools`'s `gap` and the
+  bar's `margin-left: auto` (used to push it to the row's far end) are on
+  the same axis, and a nonzero column-gap there gets double-counted by
+  the auto margin's free-space math, leaving exactly one gap's worth of
+  space unclaimed after the last item. Switched to `row-gap` (still
+  spaces Batch Actions from the bar vertically if they wrap onto separate
+  lines on a narrow viewport, without the bug).
+- Fixed: the rail-collapsed sidebar (`config.sidebar_collapsible`) had two
+  space issues — a group left open before collapsing kept rendering its
+  full submenu (every child's icon *and* label) spilling out past the
+  76px rail instead of collapsing to just the parent's own icon (a
+  `.prism-nav-item.open > .prism-nav-submenu` rule was more specific than
+  the one meant to hide it); and any menu item with no `icon:` set (see
+  [Sidebar navigation: icons & badges] in INTEGRATION.md) rendered as
+  either an empty color-highlighted box (if `.active`) or a totally blank
+  row once its label was hidden, reading as broken dead space. Menu items
+  without an icon now get a small dot instead, once collapsed.
+- Fixed: the mobile off-canvas sidebar toggle (`.prism-sidebar-mobile-toggle`,
+  ≤900px viewports) was rendered completely off-screen and unclickable —
+  it's a `position: fixed` descendant of `#header.prism-sidebar`, and that
+  element's own `transform: translateX(-100%)` (used to slide the closed
+  sidebar off-screen) made it the containing block for that fixed
+  descendant too, dragging the toggle button off-screen right along with
+  the hidden sidebar. The off-canvas slide now animates `left` instead of
+  `transform`, which carries no such side effect.
+- The "current scope + active filters" summary (ActiveAdmin core's own
+  "Search status" sidebar section, auto-added to every resource) now
+  renders as a highlighted pill bar in the same row as the Batch Actions
+  button/scope tabs, instead of inside `#sidebar`
+  (`config.active_filters_bar`, default `true`) — tinted with the theme's
+  primary color so it reads as a clear, eye-catching signal rather than
+  another gray panel. It used to get squeezed down to the same 72px icon
+  gutter as the Filters form whenever `collapsible_filters` had it
+  collapsed, and its content had nowhere to fit in 72px — it overflowed
+  out over the table instead of shrinking cleanly. Set
+  `config.active_filters_bar = false` to restore ActiveAdmin's stock
+  sidebar-based behavior.
+- Fixed: a Select2-enhanced `<select>` in the main form (`config.select2`,
+  or any field opted in individually) rendered full-width on its own line
+  below its label instead of beside it, like every other field. The BFC
+  sizing trick used to fit it into ActiveAdmin core's floated-label layout
+  only works when the element's width is `auto` — but Select2 always sets
+  an inline `width: 100%` on `.select2-container` itself (prism.js's
+  auto-init passes `{ width: "100%" }`, and a host's own manual
+  `.select2()` call hits the same code path at its default width), so that
+  trick never actually engaged. Matches ActiveAdmin core's own input width
+  instead.
+- Fixed: a field row whose label this theme deliberately doesn't float
+  (e.g. a boolean checkbox, or `as: :prism_toggle`) could let the *next*
+  row's floated label render up alongside it instead of starting on its
+  own line below, since the short row's un-cleared float left no height
+  for the next label to clear against. Every field row now clears its own
+  floats.
+
+## 0.1.2
+
+- Adds [Select2](https://select2.org) support (`config.select2`, default
+  `false` — the only opt-in-by-default flag in this gem) — reskinned to
+  match the theme, and now vendored inside the gem's own assets (no
+  separate gem/npm dependency, no JS of your own required). Turn it on to
+  auto-enhance *every* plain `<select>` (filters, form inputs, association
+  pickers) into a searchable widget with zero per-field setup; or leave it
+  off and opt individual fields in yourself the same way you would in any
+  other Rails app (`input_html: { class: "..." }` + your own `.select2()`
+  call) — both approaches coexist without double-initializing the same
+  element. Covers single-select, multi-select ("tags"/pill chips), and the
+  open dropdown/search box/results list — see
+  [Select2](INTEGRATION.md#select2) in INTEGRATION.md. Without the CSS
+  half of this, a Select2-enhanced select rendered at its tiny unstyled
+  default size, and its open dropdown could clash with the theme entirely.
+- Fixed: the collapsible Filters sidebar panel kept `overflow: hidden`
+  even while expanded, clipping/garbling any dropdown (Select2 or AA's own
+  "select + search" filter widget) that needed to render outside its own
+  input's bounds. `&.open`/the `collapsible_filters: false` backstop now
+  reset `overflow` back to `visible`.
+- Fixed: the Cancel button (and any other `fieldset.actions`/
+  `fieldset.buttons` link styled via `prism-button-secondary`) rendered
+  with ActiveAdmin's own pill-shaped `border-radius: 200px` instead of
+  Prism's — a more specific AA selector was winning on that one property
+  even though Prism's color/background already won via `!important`. Both
+  button mixins now mark `border-radius` `!important` too.
+- Fixed: form action buttons (Create/Update + Cancel) could stack
+  vertically instead of sitting side by side. ActiveAdmin lays them out
+  via `float: left` on each `<li>`, which is fragile (a longer button
+  label, or a host's own CSS, can lose the float); the actions `<ol>` is
+  now a flex row instead, which floats have no effect on regardless of
+  specificity or content width.
+
 ## 0.1.1
 
 - A search box renders at the top of the sidebar's "Pages" nav

data/INTEGRATION.md

@@ -116,6 +116,7 @@ ActiveAdminPrism.configure do |config|
   config.colorize_action_icons = true      # default: true
   config.styled_confirms = true            # default: true
   config.collapsible_filters = true        # default: true
+  config.active_filters_bar = true         # default: true
   config.sidebar_footer = true             # default: true
   config.flash_dismissible = true          # default: true
   config.flash_auto_dismiss = true         # default: true
@@ -131,6 +132,9 @@ ActiveAdminPrism.configure do |config|
     { label: "Español", locale: :es },
     { label: "Français", locale: :fr }
   ]
+  config.menu_search = true                # default: true
+  config.select2 = false                   # default: false (opt-in — see below)
+  config.sidebar_collapsible = true        # default: true
 end
 
 ActiveAdminPrism.enable!
@@ -142,6 +146,7 @@ ActiveAdminPrism.enable!
 | `colorize_action_icons`          | `true`  | Index-table View/Edit/Delete render as ActiveAdmin's plain text links instead of color-coded icon buttons. |
 | `styled_confirms`                | `true`  | Row-level `data-confirm` links (View/Edit/Delete, or anything else using Rails UJS's `data-confirm`) fall back to the browser's native `confirm()`. Batch Actions confirms are unaffected either way — they always use ActiveAdmin's own dialog. |
 | `collapsible_filters`            | `true`  | The "Filters" sidebar panel always renders fully expanded (ActiveAdmin's own default) instead of collapsing to a single icon button that expands on click. |
+| `active_filters_bar`             | `true`  | The current scope/active-filters summary renders inside `#sidebar` as its own panel (ActiveAdmin's own default) instead of as a highlighted bar beside Batch Actions — see [Active filters bar](#active-filters-bar). |
 | `sidebar_footer`                 | `true`  | "Powered by Active Admin" (or your own `config.footer`) stays in ActiveAdmin's original page-level `#footer` instead of moving into the sidebar. |
 | `flash_dismissible`              | `true`  | Flash messages render as ActiveAdmin's original plain `<div>` (no dismiss button). |
 | `flash_auto_dismiss`             | `true`  | Flash messages stay on screen until the next page load (ActiveAdmin's default) instead of disappearing on their own. |
@@ -153,6 +158,9 @@ ActiveAdminPrism.enable!
 | `login_tagline`                  | `"Sign in to your admin dashboard"` | `nil` renders no tagline at all. |
 | `language_switcher`              | `true`  | No "Languages" dropdown renders in the sidebar at all — see [Language switcher](#language-switcher). |
 | `languages`                      | 3 entries (English/Español/Français) | The list the dropdown renders; an empty array (`[]`) has the same effect as `language_switcher = false`. |
+| `menu_search`                    | `true`  | No search box renders above the sidebar's "Pages" nav — see [Menu search](#menu-search). |
+| `select2`                        | `false` | **Opposite polarity from every other flag above — opt-in, not opt-out.** `false` (the default) leaves every `<select>` exactly as ActiveAdmin renders it. `true` auto-enhances *every* plain `<select>` (filters, form inputs, association pickers — no per-field setup) into a searchable Select2 widget — see [Select2](#select2). |
+| `sidebar_collapsible`             | `true`  | No hamburger toggle button renders next to the brand — the sidebar is always full width, with no way to collapse it to an icon-only rail. Desktop-only either way; the mobile off-canvas toggle is unaffected — see [Collapsible sidebar rail](#collapsible-sidebar-rail). |
 
 **How this crosses the server/client boundary.** `sidebar`,
 `colorize_action_icons`, and the `login_*` flags are pure server-side
@@ -284,6 +292,23 @@ passes this hash through untouched) accepts: `:dashboard`, `:users`,
 `:home`, `:list`, `:folder`, `:bell`, `:search`, `:menu`, `:logout`,
 `:check`, `:x`, `:chevron_down`, `:eye`, `:pencil`, `:trash`, `:filter`.
 
+### Collapsible sidebar rail
+
+A hamburger icon button next to the brand, at the top of the sidebar,
+collapses it to a narrow icon-only rail — labels, the search box, language
+switcher, and section headings all hide, leaving just the icons (each
+still identifiable via a native tooltip on hover). Clicking again expands
+it back to full width. The choice persists across page loads
+(`localStorage`, like the per-group nav expand/collapse state already
+does). Desktop-only: below the 900px mobile breakpoint the sidebar is
+already off-canvas (a full-width drawer toggled by its own separate
+hamburger button, `.prism-sidebar-mobile-toggle`), and collapsing to a
+rail there wouldn't make sense — this toggle has no effect on that
+behavior either way. Turn it off with
+`config.sidebar_collapsible = false` to remove the toggle entirely (the
+sidebar is then always full width, ActiveAdmin's own implicit default
+before this flag existed).
+
 ### Parent groups & submenus (nested navigation)
 
 Nested groups (e.g. an "E-Commerce" group containing "Products" and
@@ -421,6 +446,40 @@ ActiveAdmin's own `Menu`/`MenuItem`/`build_menu` machinery — see
 [Language switcher markup](#language-switcher-markup) for why, and for the
 full class/id reference.
 
+### Menu search
+
+A search box renders at the top of the sidebar, between the language
+switcher (if any) and the "Pages" nav — no setup required beyond the
+default `config.menu_search = true`. It filters your existing `menu do |m|
+... end` items by label as you type; there's no server round trip and no
+change to how those blocks are authored in `app/admin/*.rb` — see
+`lib/active_admin/views/prism_sidebar.rb#render_search_box` for the markup
+and `js-src/prism.js` for the filtering logic itself.
+
+Matching is case-insensitive and works at any nesting depth, since the
+whole menu tree is already rendered up front and the filtering happens
+purely client-side over the existing DOM:
+
+- A submenu item that matches keeps its parent group visible **and
+  expanded**, even though the parent's own label doesn't match — so a
+  match buried a couple of levels deep is never hidden behind a collapsed
+  group.
+- A parent whose own label matches reveals its **entire** submenu,
+  expanded, regardless of whether any individual child also matches.
+- Items that don't match (and have no matching descendant) get
+  `.prism-nav-hidden`; if nothing in the whole nav matches, a
+  `.prism-nav-empty` "No matching menu items" message takes their place.
+
+Clearing the input — via the "x" button (`data-prism-nav-search-clear`,
+only shown while there's a query) or pressing <kbd>Escape</kbd> while the
+input has focus and a value — resets the nav back to its normal
+expand/collapse state (whatever `.open`/`.active` state it already had
+from user-toggling or the current page, unrelated to search).
+
+Turn it off with `config.menu_search = false` — no search box renders at
+all, and the "Pages" nav starts directly below the brand/language
+switcher, matching this gem's behavior before the feature existed.
+
 ### Icon helper
 
 Available anywhere in your admin views (not just the sidebar):
@@ -461,6 +520,92 @@ end
 Explicit opt-in per column/row — ActiveAdmin's default `status_tag`
 "Yes"/"No" pill is untouched everywhere you don't call it.
 
+### Select2
+
+Prism reskins [Select2](https://select2.org) — the jQuery widget that makes
+a `<select>` searchable — and ships it vendored inside its own assets
+(`vendor/select2`, MIT licensed), so there's no separate gem/npm dependency
+or JS of your own to add either way. Two ways to use it:
+
+**1. Every select, automatically — `config.select2 = true`.** Opt-in
+(default `false`, the only flag in this gem with that polarity — see
+[Configuration reference](#configuration-reference)):
+
+```ruby
+ActiveAdminPrism.configure do |config|
+  config.select2 = true
+end
+```
+
+With this on, *every* plain `<select>` ActiveAdmin renders — filters, form
+inputs, association pickers, ransack predicate dropdowns, date-part
+selects, all of it, no per-field setup — becomes a searchable Select2
+widget. There's no way to exclude individual selects from this today; if
+you only want it on specific fields, use the next approach instead.
+
+**2. Specific fields only — bring your own `.select2()` call.** Leave
+`config.select2` at its default `false` and initialize Select2 yourself,
+the same way you would in any other Rails app (this still works whether or
+not you also load your own separate copy of Select2 — Prism's vendored
+copy and a host's own don't conflict, they just both define
+`jQuery.fn.select2` and the last one loaded wins, harmlessly):
+
+```ruby
+# app/admin/teachers.rb
+filter :subject, input_html: { class: "your-select2-class" }
+
+form do |f|
+  f.input :subject, input_html: { class: "your-select2-class" }
+end
+```
+
+```js
+$(".your-select2-class").select2({ width: "100%" })
+```
+
+Either way, any element Select2 replaces picks up Prism's border/radius/
+focus-ring styling automatically, matching every other input in the
+theme; its open dropdown (search box, results list) is styled to match
+Prism's popover look — see [Select2 markup](#select2-markup) for the
+class reference. The auto-init (approach 1) skips any `<select>` a host
+already initialized manually (approach 2) — see `js-src/prism.js` — so
+the two can coexist: turn `config.select2` on globally and still hand-roll
+one particular field's Select2 options (`tags: true`, a custom
+`ajax:`, etc.) yourself, since your own `.select2()` call runs first and
+the auto-init recognizes it's already initialized.
+
+**Multi-select ("tags") mode** — e.g. a `has_many`/`has_and_belongs_to_many`
+association — is themed too, as pill-shaped chips instead of Select2's own
+default boxed/absolute-positioned look:
+
+```ruby
+f.input :subjects, as: :select, multiple: true, input_html: { class: "your-select2-class" }, collection: Subject.all
+```
+
+Everything above (width handling, dropdown styling) applies the same way
+regardless of single/multiple mode, and regardless of which of the two
+approaches initialized it.
+
+**Why width behaves differently in the sidebar Filters panel vs. a form.**
+The Filters panel and standalone filter forms stack each field's label
+above it (no float), so Select2 renders at a flat `width: 100%` there,
+matching `.sidebar_section select`'s own width rule. A `fieldset.inputs`
+form (the main new/edit form) instead floats the label to the *left* and
+gives text inputs an explicit `calc(80% - padding)` width so they sit
+beside it — a padding value this gem has no access to at compile time
+(its CSS is compiled standalone from `scss-src/*.scss`, without
+ActiveAdmin's own Sass variables in its load path; see
+[Customizing colors](#customizing-colors)). Rather than hardcode an
+equivalent, Prism gives the field its own block formatting context
+(`overflow: hidden`, no explicit width) there instead — the CSS spec
+requires a box like that not to overlap a preceding float's box, so the
+browser sizes it to exactly the remaining space automatically, no magic
+number needed. If you render a Select2 field somewhere using neither of
+these two layout conventions, you may need your own `width`/`overflow`
+override alongside it — without one, a full-width Select2 box will render
+*underneath* a floated label rather than beside it, visually hiding the
+label.
+
 ### Row-level action icons
 
 View/Edit/Delete on index pages render as color-coded icon buttons (blue
@@ -493,12 +638,46 @@ The reflow relies on the CSS `:has()` selector (broadly supported in
 current browsers); without it, the Filters panel still collapses/expands
 correctly, it just won't reclaim the extra width.
 
+### Active filters bar
+
+Once at least one filter or scope is active, a summary ("Scope: All",
+"Bank code contains BCA", etc.) renders as a highlighted pill bar in the
+same row as the Batch Actions button/scope tabs (AA core's own
+`.table_tools`, pushed to the row's far end), instead of inside
+ActiveAdmin's own `#sidebar` as its own panel. Tinted with the theme's
+primary color (a colored left border + tinted background, distinct from
+the plain gray panels elsewhere) so an active filter reads as a clear,
+eye-catching signal rather than blending in as more chrome. It's also
+clickable — clicking anywhere on it opens the Filters panel (expanding it
+if `collapsible_filters` has it collapsed) and scrolls it into view,
+a shortcut to editing the filters currently producing this exact result
+set, rather than only the separate funnel icon doing that. This is also
+the fix for that sidebar summary overflowing out whenever the collapsible
+Filters panel (above) is collapsed to its 72px icon gutter — there's
+nowhere in 72px for a sentence-length filter description to fit. Turn it
+off with `config.active_filters_bar = false` to restore ActiveAdmin's own
+stock sidebar-based rendering (only sensible if `collapsible_filters` is
+also `false`, since otherwise the two flags combined bring the overflow
+back).
+
 ### Flash messages
 
-Flash messages get a dismiss button, auto-hide after a configurable delay,
-and fade/slide out with a smooth, configurable transition — see
-[Configuration reference](#configuration-reference) for
-`flash_dismissible`, `flash_auto_dismiss(_seconds)`, and
+Flash messages render as floating toast cards, pinned to the top-right
+corner of the viewport (stacking if more than one is active) instead of
+ActiveAdmin's plain inline banner — a type-colored icon
+(`:check_circle`/`:alert_triangle`/`:alert_circle`/`:info` depending on
+the flash key: `:notice`/`:success`, `:alert`/`:warning`, `:error`, and
+anything else respectively), the message, a dismiss button, and — while
+`flash_auto_dismiss` is on — a countdown bar along the card's bottom edge
+that visually empties out over `flash_auto_dismiss_seconds`, pausing
+(along with the actual auto-dismiss timer, not just its own animation) as
+long as the pointer is over the card, so a flash a visitor is mid-read
+never vanishes out from under them. Fades/slides out with a smooth,
+configurable transition on dismiss (manual or automatic) either way. This
+applies identically on Devise's sign-in/password/etc pages — see
+[Flash messages markup](#flash-messages-markup) for why that needed its
+own layout override. See [Configuration reference](#configuration-reference)
+for `flash_dismissible`, `flash_auto_dismiss(_seconds)`, and
 `flash_transition_ms`.
 
 ### Sidebar footer ("Powered by Active Admin")
@@ -641,15 +820,24 @@ Ruby view files under `lib/active_admin/views/`.
   span.prism-sidebar-mobile-toggle       <- hamburger, ≤900px viewports only
   div.prism-sidebar-inner
     div.prism-sidebar-brand
+      span.prism-sidebar-collapse-toggle[role=button][data-prism-toggle-sidebar-collapse]  <- only if config.sidebar_collapsible
+        svg.prism-sidebar-collapse-icon <- the :menu (hamburger) icon
       #site_title                       <- AA's own site_title verb, unchanged
     div.prism-sidebar-lang              <- only if config.language_switcher and #languages is non-empty
+    div.prism-sidebar-search            <- only if config.menu_search
+      svg.prism-nav-icon.prism-search-icon
+      input.prism-nav-search-input[type=search][data-prism-nav-search]
+      span.prism-nav-search-clear[data-prism-nav-search-clear]
+        svg.prism-nav-icon              <- the :x icon
     div.prism-sidebar-scroll
       div.prism-nav-section-label       <- "PAGES"
       ul.prism-nav
         li.prism-nav-item[#prism_nav_<id>]
           [.has-children]               <- item.items.any?
           [.active]                     <- item.current?(current_tab)
-          [.open]                       <- has-children && active, or user-toggled
+          [.open]                       <- has-children && active, or user-toggled, or search match (see below)
+          [.prism-nav-hidden]           <- filtered out by menu search, toggled client-side
+          [.prism-search-open]          <- this item or a descendant matches the current search query
           span.prism-nav-group-toggle   <- only when .has-children
             svg.prism-nav-icon
             span.prism-nav-label
@@ -658,6 +846,7 @@ Ruby view files under `lib/active_admin/views/`.
             svg.prism-nav-icon
             span.prism-nav-label
           ul.prism-nav-submenu          <- only when .has-children, nested li.prism-nav-item...
+      div.prism-nav-empty[.prism-nav-empty-visible]  <- "No matching menu items", shown when search yields zero results
     div.prism-sidebar-utility           <- only if the utility menu has items
       ul.prism-nav.prism-nav-utility
         li#prism_nav_current_user
@@ -680,8 +869,16 @@ Notes:
   built-in styling of its own beyond what you see in `_sidebar.scss` — it's
   just an example class name, feel free to use your own.
 - Body-level state: `body.prism-sidebar-open` (mobile off-canvas open,
-  toggled by `prism.js`), `body.prism-sidebar-footer-disabled` (set when
-  `config.sidebar_footer` is `false` — see [Configuration reference](#configuration-reference)).
+  toggled by `prism.js`), `body.prism-sidebar-collapsed` (desktop rail
+  collapsed, also toggled by `prism.js` and persisted to `localStorage` —
+  see [Collapsible sidebar rail](#collapsible-sidebar-rail)),
+  `body.prism-sidebar-footer-disabled` (set when `config.sidebar_footer` is
+  `false` — see [Configuration reference](#configuration-reference)).
+- Every `a.prism-nav-link` / `span.prism-nav-group-toggle` also carries a
+  plain `title="<label>"` attribute (a host's own explicit `:title` via
+  `html_options` wins instead) — inert most of the time, but the only way
+  left to identify an item by hovering once `.prism-nav-label` itself is
+  hidden by the rail-collapsed state above.
 
 ### Language switcher markup
 
@@ -708,6 +905,37 @@ than being fixed at boot the way the sidebar's own header-swap
 registration is (see [Sign-in page](#sign-in-page) for the other example
 of that "built once at boot vs. re-read every request" distinction).
 
+### Menu search markup
+
+```
+div.prism-sidebar-search
+  svg.prism-nav-icon.prism-search-icon
+  input.prism-nav-search-input[type=search][data-prism-nav-search][placeholder="Search menu"]
+  span.prism-nav-search-clear[data-prism-nav-search-clear][.prism-nav-search-clear-visible]
+    svg.prism-nav-icon                          <- the :x icon
+```
+
+All filtering state lives on the existing `li.prism-nav-item` tree
+rendered by [Sidebar](#sidebar-activeadminviewsprismsidebar) — `prism.js`
+reads `[data-prism-nav-search]`'s value on every `input` event and, per
+item, toggles:
+
+- `.prism-nav-hidden` — item (and every descendant) doesn't match and has
+  no matching descendant; hidden via CSS.
+- `.prism-search-open` — item itself matches, or has a matching
+  descendant; combined with `.has-children`, this is what keeps a group
+  expanded during a search independently of its own user-toggled `.open`
+  state.
+- `.prism-nav-search-clear-visible` on the clear button, and
+  `.prism-nav-empty-visible` on `div.prism-nav-empty`, both mirroring
+  whether the query is non-empty / yields zero matches.
+
+<kbd>Escape</kbd> while the input is focused and non-empty, or a click on
+`[data-prism-nav-search-clear]`, clears the value and re-triggers the same
+filtering pass (an empty query matches everything, restoring the nav's
+prior expand/collapse state). None of this touches the server — the menu
+tree itself is rendered once, same as without `config.menu_search`.
+
 ### Panels & cards
 
 Pure CSS reskin of AA's existing `Panel`/`Component` markup — no new
@@ -774,6 +1002,39 @@ read-only tag — same pill/thumb CSS, driven by a sibling `:checked`
 selector in the form case and by the `.on`/`.off` class in the read-only
 case (there's no real `<input>` on an index/show page).
 
+### Select2 markup
+
+Only rendered if your app's own JS actually calls `.select2()` on an
+element — see [Select2](#select2). This is
+Select2's own markup, reskinned by targeting its own class names, not
+anything Prism itself renders:
+
+```
+.select2-container                          <- replaces the original (now hidden) <select>
+  .select2-selection--single                <- single-select: the visible closed-state box
+    .select2-selection__rendered            <- selected option's text
+    .select2-selection__placeholder
+    .select2-selection__arrow
+    .select2-selection__clear               <- the "x" clear button (allowClear: true)
+  .select2-selection--multiple              <- multiple: true instead — a row of pill "chips"
+    .select2-selection__rendered
+      li.select2-selection__choice          <- one per selected option
+        .select2-selection__choice__display <- its label text
+        .select2-selection__choice__remove  <- its own "x" remove button
+    .select2-search--inline
+      input.select2-search__field           <- the free-typing search box inline with the chips
+  [.select2-container--open]                <- while its dropdown is open
+  [.select2-container--focus]               <- multiple mode: while focused (not necessarily open)
+  [.select2-container--disabled]
+
+.select2-dropdown                           <- the open dropdown, appended to <body> (or `dropdownParent`)
+  .select2-search--dropdown
+    input.select2-search__field             <- the built-in search box
+  ul.select2-results
+    li.select2-results__option[.select2-results__option--highlighted][aria-selected="true"]
+    li.select2-results__message             <- "No results found" etc.
+```
+
 ### Filters sidebar panel (`#filters_sidebar_section`)
 
 Only this specific `SidebarSection` (AA's built-in id for the Filters
@@ -799,21 +1060,70 @@ panel) gets the extra icon/collapse markup — any other sidebar section
 `body.prism-filters-collapsible-disabled` is the backstop class that forces
 the panel back to always-expanded.
 
+### Active filters bar (`#prism_active_filters_bar`)
+
+Only present once at least one filter or scope is active
+(`config.active_filters_bar`, default `true` — see
+[Active filters bar](#active-filters-bar)); reuses ActiveAdmin core's own
+`ActiveAdmin::Views::ActiveFiltersSidebarContent` markup/i18n wholesale, so
+the `h4`/`b`/`ul`/`li` structure below is AA's, not Prism's own:
+
+```
+#main_content
+  .index_content
+    .table_tools                                        <- AA core's own — Batch Actions/scope tabs row
+      .table_tools_actions                               <- only if any_table_tools? — wraps the controls AA core itself renders here
+        .dropdown_menu                                    <- Batch Actions button
+        .scopes                                           <- scope tabs, if any are defined
+      #prism_active_filters_bar.prism-active-filters-bar  <- only if a scope/filter is active; pushed to the row's far end
+        h4 + b.current_scope_name                          <- only if a scope is active
+        div
+          h4                                                <- "Current filters:"
+          ul
+            li[class="current_filter_*"]                    <- one per active filter/scope value
+              span                                           <- filter label + predicate
+              b                                               <- the filter's value
+```
+
 ### Flash messages markup
 
+Rendered twice over — once from `lib/active_admin/views/flash_messages.rb`
+(Arbre, for every logged-in page) and once, identically, from
+`app/views/layouts/active_admin_logged_out.html.erb` (plain ERB, for
+Devise's sign-in/password/etc pages, which route through a completely
+separate layout ActiveAdmin itself ships rather than through
+`Pages::Base`/Arbre at all — the Ruby-side override alone never reaches
+them, which is why this gem ships a full layout override just for this).
+Both share the same icon-selection logic
+(`ActiveAdminPrism::Icons.flash_icon_name`, in `lib/prism_icons.rb`) and
+duration math (`ActiveAdminPrism::Configuration#flash_auto_dismiss_ms`)
+rather than duplicating either:
+
 ```
-.flashes[data-prism-transition-ms][data-prism-auto-dismiss-ms]
-  .flash.flash_notice / .flash_error / .flash_alert [.prism-flash-hide]
+.flashes[data-prism-transition-ms][data-prism-auto-dismiss-ms]    <- position: fixed toast stack, top-right
+  .flash.flash_notice / .flash_success / .flash_alert / .flash_warning / .flash_error / .flash_info [.prism-flash-hide]
+    [style="--prism-flash-duration: <ms>"]                         <- only if config.flash_auto_dismiss
+    svg.prism-flash-icon                                           <- :check_circle / :alert_triangle / :alert_circle / :info, by type
     span.prism-flash-message
-    button.prism-flash-dismiss[data-prism-flash-dismiss]   <- only if config.flash_dismissible
+    button.prism-flash-dismiss[data-prism-flash-dismiss]           <- only if config.flash_dismissible
       svg.prism-flash-dismiss-icon
+    div.prism-flash-progress                                       <- only if config.flash_auto_dismiss — the countdown bar
 ```
 
 `flash_notice`/`flash_error`/`flash_alert` are ActiveAdmin's own type
-classes (from `flash_messages.each { |type, ...| }`); Prism just colors
-each one distinctly. `.prism-flash-hide` is added by `prism.js` right
-before removal (opacity/transform transition), timed against the
-`data-prism-transition-ms` attribute — see
+classes (from `flash_messages.each { |type, ...| }`); `flash_success`/
+`flash_warning`/`flash_info` are the same convention extended to a host
+setting those keys directly (`flash[:warning] = "..."`, etc) — Prism
+colors each of the four icon/progress-bar combinations distinctly, all
+five type classes included. `.prism-flash-hide` is added by `prism.js`
+right before removal (opacity/transform transition), timed against the
+`data-prism-transition-ms` attribute. `.prism-flash-progress`'s width
+animates via CSS (`@keyframes prism-flash-countdown`, `transform: scaleX`)
+against the same duration `prism.js` uses for the actual removal timer —
+hovering a card pauses both in lockstep (`animation-play-state` for the
+bar, a tracked remaining-time restart for the timer itself) rather than
+just the visual, so a paused bar can't silently disagree with a flash
+that's still counting down underneath it. See
 [Flash messages](#flash-messages) / [Configuration reference](#configuration-reference).
 
 ### Confirm dialog (jQuery UI)