active_admin_prism 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 903311b452f71d21629d8bb53cd03722b1789a0fbab84f47920fd9347f03d98c
-  data.tar.gz: 81382766724dea1283fa50481b421ee8394a2f1b310c3dcfa30ed9af6ffeede9
+  metadata.gz: 34c64b9f9a4624ab0c6b5bcebd46bd4c65b220e86fa6b8095d26ee35acdb4af2
+  data.tar.gz: 72e3885c4e3f91874b6e6f99b629c3480eb4b1098de4044f12e3c6d50b95bf66
 SHA512:
-  metadata.gz: 58344d5b63d18fa7e24b0a3a8f3d4285c382a25c3b191016f9d4c02d640dc6a434a92822313056b6fe7eea2757c4358347eb3cc5f8b10e1dffdcec205434837b
-  data.tar.gz: 69bc5e4f99226abf52f76ada12054cc6a1e8816bbda267b33aa537fdf1bebe99017005e1a1b03a56688bcf2978372480eb907e77ee55193ca47535e40b8caa5c
+  metadata.gz: 230e4441cbc71b105e1abe0b0e592fa7451c070ab4be8b2d32c5acdce55f9014b3f6c2918915bff637fe568e4299243dd9362c6a303725d977d3010ddf409e59
+  data.tar.gz: 052d8bfe74e598622c5922e0e1201ccfcf574d35937c1a6af17b71c9da06c8dbcf8311ab6df7edcd97cab957f0c70a9bf7205fdbfcf61ef63b576b230ab3a16c

data/CHANGELOG.md

@@ -1,7 +1,50 @@
 # Changelog
 
-## Unreleased
+## 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
+  (`config.menu_search`, default `true`), filtering menu items as you
+  type without a server round trip. Matching works at any nesting depth:
+  a submenu item that matches keeps its parent group visible and expanded
+  even though the parent's own label doesn't match; a parent whose own
+  label matches instead reveals its entire submenu, expanded, so you
+  never have to manually open a group to find something buried in a long
+  menu. Clearing the box (or the "x" button, or Escape) resets everything
+  back to its normal expand/collapse state.
 - **The shipped `prism.css`/`prism.js` are now minified.** `bin/build-css`
   compiles with `style: :compressed` instead of `:expanded`, and a new
   `bin/build-js` (backed by the `terser` dev dependency) minifies the real

data/INTEGRATION.md

@@ -5,6 +5,11 @@ to — switching off `active_admin_prism` in a Rails app. For a quick
 start, see [README.md](README.md); this document goes deeper on every
 option and the reasoning behind it.
 
+**Live demo:** [prism-demo.onrender.com/admin](https://prism-demo.onrender.com/admin) —
+`admin@example.com` / `password`. Hosted on Render's free tier, so the
+first request after a period of inactivity can take up to a minute to
+spin up.
+
 ## Contents
 
 - [Requirements](#requirements)
@@ -126,6 +131,8 @@ 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)
 end
 
 ActiveAdminPrism.enable!
@@ -148,6 +155,8 @@ 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). |
 
 **How this crosses the server/client boundary.** `sidebar`,
 `colorize_action_icons`, and the `login_*` flags are pure server-side
@@ -416,6 +425,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):
@@ -456,6 +499,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
@@ -638,13 +767,20 @@ Ruby view files under `lib/active_admin/views/`.
     div.prism-sidebar-brand
       #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
@@ -653,6 +789,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
@@ -703,6 +840,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
@@ -769,6 +937,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

data/README.md

@@ -9,6 +9,19 @@ no manual asset manifest edits.
 (configuration reference, feature-by-feature usage, switching/disabling the
 theme, troubleshooting). This README is a quick start.
 
+## Live demo
+
+A live demo dashboard is running at
+**[prism-demo.onrender.com/admin](https://prism-demo.onrender.com/admin)**:
+
+```
+Username: admin@example.com
+Password: password
+```
+
+The demo is hosted on Render's free tier, so the first request after a
+period of inactivity can take up to a minute while the instance spins up.
+
 ## Requirements
 
 - ActiveAdmin `>= 3.0, < 4`
@@ -16,7 +29,6 @@ theme, troubleshooting). This README is a quick start.
 - Ruby `>= 3.1`
 
 ## Install
-
 Add to your Gemfile:
 
 ```ruby
@@ -104,6 +116,8 @@ ActiveAdminPrism.configure do |config|
     { label: "Español", locale: :es },
     { label: "Français", locale: :fr }
   ]
+  config.menu_search = true             # search box that filters the sidebar's Pages nav
+  config.select2 = false                # default: false — auto-enhance every <select> into Select2
 end
 
 ActiveAdminPrism.enable!
@@ -166,6 +180,22 @@ endpoint that sets the locale server-side:
 
 Turn the whole thing off with `config.language_switcher = false`.
 
+## Menu search
+
+A search box renders at the top of the sidebar's "Pages" nav, filtering
+menu items by label as you type — pure client-side DOM filtering, no
+server round trip, no change to how you write `menu do |m| ... end` in
+`app/admin/*.rb`.
+
+Matching works at any nesting depth: a submenu item that matches keeps its
+parent group visible and expanded even though the parent's own label
+doesn't match, and a parent whose own label matches reveals its entire
+submenu, expanded. Clearing the box (the "x" button, or <kbd>Escape</kbd>)
+resets everything back to its normal expand/collapse state. No matches
+shows a "No matching menu items" message in place of the nav.
+
+Turn it off with `config.menu_search = false`.
+
 ## Toggle switches
 
 Boolean fields render as regular (reskinned) checkboxes by default. Opt in
@@ -204,6 +234,35 @@ It's an explicit opt-in per column/row (like everything else in Prism) —
 ActiveAdmin's default boolean rendering 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, so
+there's no separate gem/npm dependency to add. Turn it on for every select,
+no per-field setup:
+
+```ruby
+ActiveAdminPrism.configure do |config|
+  config.select2 = true   # default: false — opt-in, unlike every other flag
+end
+```
+
+...or leave that off and opt individual fields in yourself instead, same as
+you would in any other Rails app:
+
+```ruby
+filter :subject, input_html: { class: "your-select2-class" }
+# or: f.input :subject, input_html: { class: "your-select2-class" }
+```
+
+```js
+$(".your-select2-class").select2({ width: "100%" })
+```
+
+See [INTEGRATION.md](INTEGRATION.md#select2) for how the two approaches
+coexist, and why the sidebar Filters panel and a main form need different
+`width` handling under the hood.
+
 ## Sign-in page
 
 Every Devise auth page (sign in, sign up, forgot/reset password, resend