madmin 2.6.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35abef3e18e33da02efc68140fbbffe237a15b5054f99a6299265b1219181069
-  data.tar.gz: 6cd25c564e51d1d663b9b8525caa793d6395e8534f831a02fdf41b36411b6161
+  metadata.gz: 502a8cbe4b6c86b1fa6f45d2f4d0f1f5b7852b48805a8d980cfb177ed4151c51
+  data.tar.gz: 41d8fbfd222f0758f81e2b90762d54ddbefd279ebd18b455ac2def6bd2a60e1e
 SHA512:
-  metadata.gz: 62b04e88f49fbbb3c680c482e6c73bfa71710471c858e872f11d8eb5ba6491fb8c12607adadea92f64c8ed3f1b6da10afa616fa3e13114dbe0a2a5365d41c897
-  data.tar.gz: 3e11e615a5720928b8997fa684549a2e67cc17e06d689a0856ba9d350d6037ccb63d6f6dd543e353712ce32616f8af09efbe66dfa545a91eae7cef98896cb6fe
+  metadata.gz: c390c0a27fcfe25bee8b1ab32f7d53644cc68cad9ee386f17adf810839a511212dfa7fe821cf275edd63a95d1dccbdbeffb22bad56f1ffa5db6c0e67e56d3a74
+  data.tar.gz: be7ec1e7fa71db380147c44f154e539e56719b35be488f7068473dfccfeeba44175abb58ee281bf4eb1089ab8a188eb5b66c0e5d46d847f639f1bbe15895107d

data/README.md

@@ -7,11 +7,14 @@
 Why another Ruby on Rails admin? We wanted an admin that was:
 
 - Familiar and customizable like Rails scaffolds (less DSL)
-- Supports all the Rails features out of the box (ActionText, ActionMailbox, has_secure_password, etc)
-- Stimulus / Turbolinks / Hotwire ready
-- Works with Import maps and Sprockets
+- Supports Rails features out of the box (Action Text, Active Storage, Action Mailbox, has_secure_password, etc)
+- Built with Hotwire: Turbo, Stimulus and import maps, with no Node or build step
+- Search, filters and scopes on index pages, and dark mode
+- Works with Propshaft and Sprockets
 
-![Madmin Screenshot](docs/images/screenshot.png)
+![Madmin index page with filters](docs/images/index.png)
+
+![Madmin edit form in dark mode, searching for a user](docs/images/edit-dark.png)
 
 ## Installation
 
@@ -72,6 +75,66 @@ end
 
 The new, edit, and delete links are hidden for read-only resources, and any write actions redirect back to the index.
 
+### Scopes
+
+Declare scopes on a resource to render filter buttons on the index page. Each scope must be a scope or class method on the model:
+
+```ruby
+class PostResource < Madmin::Resource
+  scope :published
+  scope :draft
+end
+```
+
+Button labels default to the humanized scope name. To customize or translate them, define an I18n key — `madmin.scopes.<param_key>.<scope>` for one resource, or `madmin.scopes.<scope>` shared across resources:
+
+```yaml
+en:
+  madmin:
+    scopes:
+      post:
+        published: Live
+```
+
+### Filters
+
+Index pages have a Filters button for narrowing records by their columns, like "Admin is true" or "Created at after Aug 15". Filters combine with search, scopes and sorting, and they're kept in the URL so filtered lists can be bookmarked and shared.
+
+String, text, number, date, datetime and boolean columns can be filtered. Encrypted columns and attributes that aren't database columns are left out. Turn filtering off for an attribute with `filter: false`:
+
+```ruby
+class UserResource < Madmin::Resource
+  attribute :api_token, filter: false
+end
+```
+
+Custom fields can offer a filter by returning `:string`, `:number`, `:date`, `:datetime` or `:boolean` from `self.filter_type`.
+
+### Resource Names
+
+Resource names in the menu, headings and buttons come from the model's translation when it has one, so they follow Rails' own `activerecord.models` keys:
+
+```yaml
+en:
+  activerecord:
+    models:
+      post:
+        one: Article
+        other: Articles
+```
+
+Models without a translation keep their default names, like `Posts` and `Active Storage / Blobs`.
+
+For labels that need logic (e.g. looking up a record name), override `scope_label`:
+
+```ruby
+class PostResource < Madmin::Resource
+  def self.scope_label(name)
+    name.to_s.titleize
+  end
+end
+```
+
 ## Configuring Views
 
 The views packaged within the gem are a great starting point, but inevitably people will need to be able to customize those views.
@@ -147,6 +210,25 @@ class BookResource < Madmin::Resource
 end
 ```
 
+### Nested Forms
+
+Use `:nested_has_many` or `:nested_has_one` to edit associated records inside the parent's form. The model needs `accepts_nested_attributes_for`, with `allow_destroy: true` for the Remove link to work, and the associated model needs a resource. Use `skip` to leave out attributes of the associated resource:
+
+```ruby
+class User < ApplicationRecord
+  has_many :posts
+  has_one :profile
+  accepts_nested_attributes_for :posts, :profile, allow_destroy: true
+end
+
+class UserResource < Madmin::Resource
+  attribute :posts, :nested_has_many, skip: %I[user]
+  attribute :profile, :nested_has_one, skip: %I[user]
+end
+```
+
+A nested has one shows its fields when the record exists, or an "Add" link when it doesn't, so saving the parent doesn't create an empty record.
+
 ## Custom Fields
 
 You can generate a custom field with:
@@ -250,6 +332,27 @@ Hooks registered after a class has already loaded run immediately, so ordering i
 You can use a couple of strategies to authenticate users who are trying to
 access your madmin panel: [Authentication Docs](docs/authentication.md)
 
+## Dark Mode
+
+Madmin follows the system's light or dark setting. To always use one, add a stylesheet with `Madmin.stylesheets << "madmin_overrides"` (see [Assets](docs/assets.md)) and set `color-scheme`:
+
+```css
+:root {
+  color-scheme: light;
+}
+```
+
+Madmin's colors are CSS variables on `:root`, defined with `light-dark()` so each has a light and a dark value. Custom fields and views can use them to match both modes, and you can override them to change the theme:
+
+```css
+:root {
+  --primary-color: rgb(79 70 229); /* Button backgrounds */
+  --link-color: light-dark(rgb(79 70 229), rgb(129 140 248));
+}
+```
+
+The variables are `--primary-color`, `--link-color`, `--text-color`, `--light-text-color`, `--surface-color` (page and input backgrounds), `--background-color` (table headers), `--hover-color`, `--border-color`, `--input-border-color` and `--danger-color`.
+
 ## Assets
 You can customize the JavaScript and CSS assets used by Madmin for your application. To learn how
 see the [Assets Doc](docs/assets.md)

data/app/assets/stylesheets/madmin/actiontext.css

@@ -29,3 +29,34 @@
   padding: 0 !important;
   max-width: 100% !important;
 }
+
+/* Trix draws its toolbar icons in black, so its buttons stay light */
+trix-toolbar .trix-button-group {
+  background: light-dark(transparent, rgb(209 213 219));
+}
+
+trix-toolbar .trix-dialog {
+  background: var(--background-color);
+}
+
+/* Lexxy has no dark palette. `html:root` outranks Lexxy's own :root variables, which load after Madmin's */
+html:root {
+  --lexxy-color-ink: light-dark(oklch(20% 0 0), var(--text-color));
+  --lexxy-color-ink-medium: light-dark(oklch(40% 0 0), rgb(209 213 219));
+  --lexxy-color-ink-light: light-dark(oklch(60% 0 0), var(--light-text-color));
+  --lexxy-color-ink-lighter: light-dark(oklch(85% 0 0), var(--border-color));
+  --lexxy-color-ink-lightest: light-dark(oklch(96% 0 0), var(--background-color));
+  --lexxy-color-ink-inverted: var(--surface-color);
+
+  --lexxy-color-accent-light: light-dark(oklch(88% 0.026 254), rgb(30 64 175));
+  --lexxy-color-accent-lightest: light-dark(oklch(92% 0.026 254), rgb(30 58 138));
+
+  --lexxy-color-code-token-att: light-dark(#d73a49, #f97583);
+  --lexxy-color-code-token-comment: light-dark(#6a737d, #959da5);
+  --lexxy-color-code-token-function: light-dark(#6f42c1, #b392f0);
+  --lexxy-color-code-token-operator: light-dark(#d73a49, #f97583);
+  --lexxy-color-code-token-property: light-dark(#005cc5, #79b8ff);
+  --lexxy-color-code-token-punctuation: light-dark(#24292e, #e1e4e8);
+  --lexxy-color-code-token-selector: light-dark(#22863a, #85e89d);
+  --lexxy-color-code-token-variable: light-dark(#e36209, #ffab70);
+}

data/app/assets/stylesheets/madmin/base.css

@@ -1,13 +1,23 @@
 :root {
+  /* Follows the system setting. Set `color-scheme: light` or `dark` on :root to force one */
+  color-scheme: light dark;
+
+  /* Button backgrounds, with white text */
   --primary-color: rgb(37 99 235);
-  --border-color: rgb(229 231 235);
-  --background-color: rgb(249 250 251);
-  --text-color: rgb(2 6 23);
-  --light-text-color: rgb(71 85 105);
+  --link-color: light-dark(rgb(37 99 235), rgb(96 165 250));
+  --border-color: light-dark(rgb(229 231 235), rgb(55 65 81));
+  --input-border-color: rgb(156 163 175);
+  --surface-color: light-dark(white, rgb(17 24 39));
+  --background-color: light-dark(rgb(249 250 251), rgb(31 41 55));
+  --hover-color: light-dark(rgb(243 244 246), rgb(31 41 55));
+  --text-color: light-dark(rgb(2 6 23), rgb(243 244 246));
+  --light-text-color: light-dark(rgb(71 85 105), rgb(156 163 175));
+  --danger-color: light-dark(rgb(239 68 68), rgb(248 113 113));
   --sidebar-width: 16rem;
 }
 
 body {
+  background-color: var(--surface-color);
   color: var(--text-color);
   font-size: 14px;
   -webkit-font-smoothing: antialiased;
@@ -19,7 +29,7 @@ body {
 }
 
 a {
-  color: var(--primary-color);
+  color: var(--link-color);
 }
 
 .size-5 {
@@ -46,8 +56,8 @@ a {
   }
 
   &.alert-danger {
-    background-color: oklch(.936 .032 17.717);
-    color: oklch(.444 .177 26.899);
+    background-color: light-dark(oklch(.936 .032 17.717), oklch(.258 .092 26.042));
+    color: light-dark(oklch(.444 .177 26.899), oklch(.885 .062 18.334));
 
     svg {
       color: oklch(.637 .237 25.331);
@@ -55,13 +65,14 @@ a {
   }
 
   &.alert-notice {
-    background-color: oklch(.962 .044 156.743);
-    color: oklch(.448 .119 151.328);
+    background-color: light-dark(oklch(.962 .044 156.743), oklch(.266 .065 152.934));
+    color: light-dark(oklch(.448 .119 151.328), oklch(.925 .084 155.995));
 
     svg {
       color: oklch(.723 .219 149.579);
     }
   }
+
 }
 
 .search {
@@ -104,14 +115,14 @@ a {
 
 
   .metric {
-    border: 1px solid rgb(229 231 235);
+    border: 1px solid var(--border-color);
     border-radius: 0.25rem;
     padding: 1rem;
     margin: 1rem;
     flex: 1 1 0%;
 
     h4 {
-      color: rgb(75 85 99);
+      color: var(--light-text-color);
       font-weight: 600;
       margin-top: 0;
       margin-bottom: 0.5rem;

data/app/assets/stylesheets/madmin/buttons.css

@@ -28,26 +28,26 @@
   }
 
   &.btn-secondary {
-    background-color: white;
-    color: rgb(31 41 55);
-    box-shadow: inset 0 0 0 1px rgb(156 163 175);
+    background-color: var(--surface-color);
+    color: var(--text-color);
+    box-shadow: inset 0 0 0 1px var(--input-border-color);
 
     &:hover {
-      background-color: rgb(243 244 246);
+      background-color: var(--hover-color);
     }
 
     &.active {
-      background-color: rgb(243 244 246);
+      background-color: var(--hover-color);
     }
   }
 
   &.btn-danger {
-    background-color: white;
-    color: rgb(239 68 68);
-    box-shadow: inset 0 0 0 1px rgb(239 68 68);
+    background-color: var(--surface-color);
+    color: var(--danger-color);
+    box-shadow: inset 0 0 0 1px var(--danger-color);
 
     &:hover {
-      background-color: rgb(243 244 246);
+      background-color: var(--hover-color);
     }
   }
 }

data/app/assets/stylesheets/madmin/forms.css

@@ -1,5 +1,5 @@
 .error {
-  color: rgb(239 68 68);
+  color: var(--danger-color);
 }
 
 .form-hint {
@@ -20,7 +20,7 @@
 }
 
 label {
-  color: rgb(17 24 39);
+  color: var(--text-color);
   line-height: 1.5rem;
   font-weight: 500;
   font-size: 0.875rem;
@@ -62,10 +62,10 @@ select {
   -webkit-appearance: none;
   -moz-appearance: none;
   appearance: none;
-  background-color: #fff;
+  background-color: var(--surface-color);
 
   border-radius: 0.375rem;
-  box-shadow: inset 0 0 0 1px rgb(156 163 175);
+  box-shadow: inset 0 0 0 1px var(--input-border-color);
   line-height: 1.5rem;
   padding-bottom: 0.375rem;
   padding-left: 0.75rem;
@@ -73,18 +73,274 @@ select {
   padding-top: 0.375rem;
 
   &:focus {
-    box-shadow: inset 0 0 0 1px rgb(var(--primary-color));
+    box-shadow: inset 0 0 0 1px var(--primary-color);
   }
 }
 
 .required {
-  color: rgb(239 68 68);
+  color: var(--danger-color);
   font-weight: 600;
 }
 
 .nested-fields {
-  border: 1px solid #e5e7eb;
+  border: 1px solid var(--border-color);
   border-radius: 0.5rem;
   padding: 1.25rem;
   margin-bottom: 1rem;
 }
+
+/* Native selects lose their arrow with `appearance: none` */
+select:not([multiple]) {
+  background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 20 20'%3e%3cpath stroke='%239ca3af' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.5' d='M6 8l4 4 4-4'/%3e%3c/svg%3e");
+  background-position: right 0.5rem center;
+  background-repeat: no-repeat;
+  background-size: 1.5em 1.5em;
+  padding-right: 2.5rem;
+}
+
+/* Combobox (select_controller.js) */
+.combobox {
+  position: relative;
+}
+
+.combobox-control {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.25rem;
+  background-color: var(--surface-color);
+  border-radius: 0.375rem;
+  box-shadow: inset 0 0 0 1px var(--input-border-color);
+  padding: 0.375rem 0.75rem;
+  cursor: text;
+
+  &:focus-within {
+    box-shadow: inset 0 0 0 1px var(--primary-color);
+  }
+}
+
+.combobox .combobox-input,
+.combobox .combobox-input:focus {
+  flex: 1;
+  min-width: 8rem;
+  background: transparent;
+  box-shadow: none;
+  outline: none;
+  padding: 0;
+}
+
+.combobox-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  background-color: var(--hover-color);
+  border-radius: 0.25rem;
+  padding-left: 0.5rem;
+  font-size: 0.875rem;
+
+  button {
+    background: none;
+    border: none;
+    color: var(--light-text-color);
+    cursor: pointer;
+    padding: 0 0.5rem;
+
+    &:hover {
+      color: var(--text-color);
+    }
+  }
+}
+
+.combobox-listbox {
+  position: absolute;
+  z-index: 10;
+  top: 100%;
+  left: 0;
+  right: 0;
+  margin-top: 0.25rem;
+  max-height: 16rem;
+  overflow-y: auto;
+  list-style: none;
+  padding: 0.25rem 0;
+  background-color: var(--surface-color);
+  border: 1px solid var(--border-color);
+  border-radius: 0.375rem;
+  box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+
+  &[hidden] {
+    display: none;
+  }
+
+  li {
+    padding: 0.375rem 0.75rem;
+    cursor: pointer;
+  }
+
+  [aria-selected="true"] {
+    background-color: var(--hover-color);
+  }
+
+  .combobox-empty {
+    color: var(--light-text-color);
+    cursor: default;
+  }
+}
+
+/* Index filters (filters_controller.js) */
+.filters-count {
+  background-color: var(--primary-color);
+  border-radius: 999px;
+  color: white;
+  display: inline-block;
+  font-size: 0.75rem;
+  line-height: 1.125rem;
+  margin-left: 0.25rem;
+  min-width: 1.125rem;
+  padding: 0 0.3rem;
+  text-align: center;
+}
+
+.filters {
+  background-color: var(--surface-color);
+  border: 1px solid var(--border-color);
+  border-radius: 0.5rem;
+  box-shadow: 0 10px 25px -5px rgb(0 0 0 / 0.2);
+  color: var(--text-color);
+  inset: auto;
+  margin: 0;
+  padding: 1rem;
+  right: 1rem;
+  top: 4.5rem;
+  width: min(44rem, calc(100vw - 2rem));
+}
+
+/* Place it under the button where anchor positioning is supported */
+@supports (position-anchor: --filters) {
+  #filters-button {
+    anchor-name: --filters;
+  }
+
+  .filters {
+    position-anchor: --filters;
+    right: anchor(right);
+    top: calc(anchor(bottom) + 0.5rem);
+
+    /* Phones use the full width instead of lining up with the button */
+    @media (max-width: 767px) {
+      left: 1rem;
+      right: 1rem;
+      width: auto;
+    }
+  }
+}
+
+.filters-heading {
+  font-weight: 600;
+  margin: 0 0 0.75rem;
+}
+
+.filter-rows {
+  display: grid;
+  gap: 0.5rem;
+}
+
+.filter-row {
+  align-items: center;
+  display: grid;
+  gap: 0.5rem;
+  grid-template-columns: minmax(0, 1.1fr) minmax(0, 1fr) minmax(0, 1.2fr) auto;
+
+  select, input {
+    min-width: 0;
+    width: 100%;
+  }
+
+  .filter-remove {
+    grid-column: 4;
+    grid-row: 1;
+  }
+
+  @media (max-width: 767px) {
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) auto;
+
+    input {
+      grid-column: 1 / 3;
+    }
+
+    .filter-remove {
+      grid-column: 3;
+    }
+  }
+}
+
+.filter-remove {
+  background: none;
+  border: none;
+  border-radius: 0.375rem;
+  color: var(--light-text-color);
+  cursor: pointer;
+  font-size: 1.125rem;
+  height: 2rem;
+  width: 2rem;
+
+  &:hover {
+    background-color: var(--hover-color);
+    color: var(--danger-color);
+  }
+}
+
+.filters-footer {
+  align-items: center;
+  border-top: 1px solid var(--border-color);
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  justify-content: space-between;
+  margin-top: 0.875rem;
+  padding-top: 0.875rem;
+}
+
+.btn.btn-link {
+  background: none;
+  color: var(--link-color);
+  font-weight: 500;
+  padding-left: 0.25rem;
+  padding-right: 0.25rem;
+}
+
+.active-filters {
+  align-items: center;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin-bottom: 1rem;
+}
+
+.filter-chip {
+  align-items: center;
+  background-color: light-dark(rgb(239 246 255), rgb(30 41 82));
+  border-radius: 999px;
+  color: light-dark(rgb(30 64 175), rgb(191 219 254));
+  display: inline-flex;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  gap: 0.25rem;
+  padding: 0.125rem 0.25rem 0.125rem 0.75rem;
+
+  strong {
+    font-weight: 600;
+  }
+
+  a {
+    border-radius: 999px;
+    color: inherit;
+    line-height: 1.5rem;
+    text-align: center;
+    text-decoration: none;
+    width: 1.5rem;
+
+    &:hover {
+      background-color: var(--surface-color);
+    }
+  }
+}

data/app/assets/stylesheets/madmin/pagination.css

@@ -2,7 +2,7 @@
   padding: 0.5rem;
 }
 
-.pagy {
+.pagination .pages {
   display: inline-flex;
   isolation: isolate;
   border-radius: 0.375rem;
@@ -17,21 +17,21 @@
     align-items: center;
     box-shadow: var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);
     --tw-ring-inset: inset;
-    --tw-ring-color: #D1D5DB;
+    --tw-ring-color: var(--input-border-color);
     font-size: 0.875rem;
     line-height: 1.25rem;
-    color: #111827;
-    background-color: #ffffff;
+    color: var(--text-color);
+    background-color: var(--surface-color);
     border-radius: 0.25rem;
     text-decoration: none;
   }
 
   a:hover {
-    background-color: #F3F4F6;
+    background-color: var(--hover-color);
   }
 
-  a:not([href]) {
-    color: #D1D5DB;
+  a[aria-disabled="true"] {
+    color: var(--input-border-color);
     cursor: default;
   }
 
@@ -39,21 +39,8 @@
     color: #ffffff;
     background-color: var(--primary-color);
   }
+}
 
-  label {
-    display: inline-block;
-    padding-top: 0.125rem;
-    padding-bottom: 0.125rem;
-    padding-left: 0.75rem;
-    padding-right: 0.75rem;
-    border-radius: 0.5rem;
-    white-space: nowrap;
-    background-color: #E5E7EB;
-  }
-
-  label input {
-    border-radius: 0.375rem;
-    border-style: none;
-    background-color: #F3F4F6;
-  }
+.pagination-info {
+  margin-left: 0.5rem;
 }

data/app/assets/stylesheets/madmin/reset.css

@@ -2,7 +2,7 @@
   box-sizing: border-box;
   border-width: 0;
   border-style: solid;
-  border-color: #e5e7eb;
+  border-color: var(--border-color, #e5e7eb);
 }
 
 body {