active_admin_theme 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a75c79a18d9bfc4496a7a904b69b6c67793e99cef416efc2d83f940288126044
-  data.tar.gz: 7c2f5832d4eba831188aca71c2655629593028aeb52df3ce8dfef16098ea414b
+  metadata.gz: c393033738086398f691d3a9e754ece92f10ab6c647dd0357da38fc5167e4368
+  data.tar.gz: 6733dc12d9ceca058b15072be3826989334e106be7db5fd273017871e258ec41
 SHA512:
-  metadata.gz: 955af2c21c919bfc020cfa9cfcd6ddbd6509484002c2e4923e2270b1b3cec0f2c48ea795193550996e89b9c616c9812c959cdfc9a70c91a4e9a90e3783b7dc79
-  data.tar.gz: c1335fa69158330d170d9ea3f03a9811f11028c8b796410dd23b2658e747e78931ee574ec5ba33f0b2dc254ff8148e25aac6666179a9dce2a43b794221eabb0f
+  metadata.gz: 2c9c40332a46b50fd79f0d1959a2cb25c4ff23ac12be1dce88b721cfcafcbc798b9971f6cb17a4ee088985a08fdac8e1cba55275579bee8ed892eb50e23a051c
+  data.tar.gz: e1973bc1eb334a1f14cb4dd46094b1c802f0074243ac89ff30aaea894b84a744a5cce42b517feb63cc083b429517fd851ac41dc391a686a9d60cb732ff170e18

data/README.md

@@ -35,7 +35,7 @@ Or add manually to `package.json`:
 
 ```
 "dependencies": {
-  "@activeadmin-plugins/active_admin_theme": "^2.0.0"
+  "@activeadmin-plugins/active_admin_theme": "^3.0.0"
 }
 ```
 and execute:
@@ -57,22 +57,255 @@ In your base stylesheet entry point `active_admin.scss` (as example), add line:
 @import '@activeadmin-plugins/active_admin_theme';
 ```
 
-You can change basic colors of the theme by setting some variable above active_admin_theme import line in active_admin.css.scss
+## Customising
 
-```css
-...
-$skinMainFirstColor: #A5A7AA!default;
-$skinMainSecondColor: #0066CC!default;
-$skinBorderWindowColor: #B8BABE!default;
+Set any of the variables below *above* the import line:
+
+```scss
+$skinMainFirstColor: #A5A7AA;
+$skinMainSecondColor: #0066CC;
+$skinBorderWindowColor: #B8BABE;
+
+@import 'wigu/active_admin_theme';
+```
+
+Variables are typed. A value of the wrong kind — `none` where a colour is
+expected, or a length without its unit — fails the build with a message
+naming the variable, instead of silently emitting CSS the browser discards.
+
+### Dark mode
+
+The theme follows the operating system via `prefers-color-scheme`, and can be
+pinned per page with `data-theme="light"` or `data-theme="dark"` on `<html>`.
+Every colour below that has a `…Dark` twin is what dark mode uses; each twin
+defaults to its light counterpart unless noted, so a project that only sets
+the light value keeps one consistent colour in both modes.
+
+### A worked example
+
+The defaults are the configuration this theme is run with in
+[yeti-web](https://github.com/yeti-switch/yeti-web). To go back to the blue
+header the theme shipped before:
+
+```scss
+$skinMenuPillColor:          $skinMainSecondColor;
+$skinMenuPanelColor:         $skinMainSecondColor;
+$skinMenuTextColor:          #ffffff;
+$skinMenuItemHoverColor:     transparent;
+$skinMenuItemHoverTextColor: #ffffff;
+$skinMenuFontSize:           1em;
+$skinHeaderPaddingY:         7px;       // one value top and bottom
+$skinTitleBarColor:          lighten($skinMainFirstColor, 8%);
+$skinTitleBarBorderWidth:    3px;
+$skinPanelHeaderColor:       $skinMainSecondColor;
+$skinPanelHeaderTextColor:   #ffffff;
+$skinTabInactiveColor:       $skinMainSecondColor;
+$skinInactiveTabTextColor:   #ffffff;
+$skinLinkColor:              $skinMainSecondColor;
 
 @import 'wigu/active_admin_theme';
-...
 ```
 
+Note `var(--aa-page-bg)` works as a variable value: a custom property follows
+the mode on its own, so one line covers both themes.
+
+### Switching themes
+
+The stylesheet follows the operating system on its own and honours
+`data-theme="light"` or `data-theme="dark"` on `<html>`. A switch is optional
+and ships with the gem:
+
+```scss
+// app/assets/javascripts/active_admin.js
+//= require wigu/theme_toggle
+```
+
+```js
+// or, as an npm module
+import "@activeadmin-plugins/active_admin_theme/src/theme_toggle";
+```
+
+A gem cannot add a menu item: ActiveAdmin builds the utility navigation from
+the host application's initializer, and nothing in a stylesheet or an asset
+runs at that point. So with nothing else to do, the script injects its own
+`li#theme_toggle` into `#utility_nav` on load. That works, but the item is
+inserted before the server-rendered ones and is not yours to order or hide.
+
+Declaring it yourself costs four lines and puts it under your control — this is
+how [yeti-web](https://github.com/yeti-switch/yeti-web) does it:
+
+```ruby
+# config/initializers/active_admin.rb
+config.namespace :admin do |admin|
+  admin.build_menu :utility_navigation do |menu|
+    # A real url, not "#": ActiveAdmin drops a blank utility item.
+    menu.add id: "theme_toggle", label: "", url: "#theme",
+             priority: 9_999_998, html_options: { role: "button" }
+  end
+end
+```
+
+The script finds `#theme_toggle` or anything carrying `.dark-mode-toggle`,
+binds by delegation — so the control survives a re-render — and writes nothing
+to the page but `data-mode`. Everything visible comes from the stylesheet.
+
+[![Theme switch](./img/switch.png)](./img/switch.png)
+
+Below the two pages: the three states at rest — half circle for **auto**, sun
+for **light**, moon for **dark** — then the last two hovered. A click moves to
+the next state, so the control costs the width of one icon in a header that is
+usually already full. The title says where that click goes, since one icon
+cannot show both.
+
+`auto` removes the attribute, so the media query decides and the page follows
+the operating system live; the other two pin the choice in `localStorage` under
+`aa-theme`. The third state is there so that following the system stays
+reachable: a two-state toggle writes a preference on the first click and has no
+way back short of clearing storage by hand.
+
+The glyphs are inline SVG used as a CSS `mask`, so the gem still ships no image
+files, there is nothing for a host application's CSP to allow, and the icon
+takes `currentColor` — `$skinMenuTextColor` like the rest of the bar, and the
+hover colour on hover. To use your own icon font instead, override
+`$theme-icon-auto` / `$theme-icon-light` / `$theme-icon-dark`, or restyle
+`#theme_toggle > a:before` outright.
+
+The control is a link with no destination, so <kbd>Tab</kbd> reaches it and
+<kbd>Enter</kbd> and <kbd>Space</kbd> operate it. Changing the theme in one tab
+applies it in the others.
+
+### Upgrading
+
+Two things changed shape in this release and are worth knowing if you already
+set variables:
+
+* Dropdown panels — the title-bar menu, the batch-actions menu and the
+  table-tools menus — now follow the surface palette (`$skinSurfaceColor` and
+  friends) instead of `$skinMainFirstColor` / `$skinMainSecondColor`. That is
+  what lets them work in both modes. If you branded those panels through the
+  two main colours, point `$skinSurfaceColor` and `$skinSurfaceHoverColor` at
+  the same values.
+* The primary button fill is darker (`darken($skinMainSecondColor, 20%)` rather
+  than the accent itself). White on the accent is 2.74:1, under the 4.5:1 small
+  text needs, and dark mode was already using this tone — the button is now one
+  colour in both modes. Set `$skinButtonColor: $skinMainSecondColor;` for the
+  old look.
+* The default content link colour is darker (`#1f5f8d` rather than the accent).
+  The accent is a fill colour and failed WCAG AA as body text. Set
+  `$skinLinkColor` back to `$skinMainSecondColor` if you prefer the old look.
+
+### Variables
+
+#### Core
+
+| Variable | Default (light / dark) | |
+|---|---|---|
+| `$skinMainFirstColor` | `#23282f` |  |
+| `$skinMainSecondColor` | `#5ea3d3` |  |
+| `$skinBorderRadius` | `4px` |  |
+| `$skinBorderWindowColor` | `#e6e9ee` |  |
+| `$skinTablePadding` | `10px` |  |
+
+#### Surfaces, text and borders
+
+| Variable | Default (light / dark) | |
+|---|---|---|
+| `$skinPageBgColor` / `$skinPageBgColorDark` | `#f7f9fb` / `#161a1e` | page background |
+| `$skinSurfaceColor` / `$skinSurfaceColorDark` | `#ffffff` / `#25292f` | panels / cards / content |
+| `$skinSurface2Color` / `$skinSurface2ColorDark` | `#f0f2f5` / `#2c3137` | table headers / striping / subtle fills |
+| `$skinSurfaceHoverColor` / `$skinSurfaceHoverColorDark` | `#f5f7fa` / `#3f454d` | row / item hover |
+| `$skinSelectedRowColor` / `$skinSelectedRowColorDark` | `#d9e4ec` / `#304457` | checked table row |
+| `$skinElevatedColor` / `$skinElevatedColorDark` | `$skinSurfaceColor` / `#363c43` | tool buttons and dropdown panels floating above the page |
+| `$skinTextColor` / `$skinTextColorDark` | `#323537` / `#dde2e8` | body text |
+| `$skinTextMutedColor` / `$skinTextMutedColorDark` | `#6b7177` / `#b0b8c2` | secondary text / axis labels |
+| `$skinBorderColor` / `$skinBorderColorDark` | `#e0e4e9` / `#404750` | borders / grid lines |
+| `$skinInputBgColor` / `$skinInputBgColorDark` | `#ffffff` / `#1e2227` | form control background |
+| `$skinInputBorderColor` / `$skinInputBorderColorDark` | `#c9ced4` / `#4d555f` | form control border |
+
+#### Header menu
+
+| Variable | Default (light / dark) | |
+|---|---|---|
+| `$skinMenuPillColor` | `#2e3236` | top-level current/hover pill |
+| `$skinMenuPillTextColor` | `#6cb0de` | text on that pill; follows the dropdown text so a |
+| `$skinMenuPanelColor` | `#2e3236` | dropdown panel bg + hover "bridge" border |
+| `$skinMenuTextColor` | `#dfe2e6` | dropdown item text (was: inherited #fff) |
+| `$skinMenuItemHoverColor` | `#3f454c` | dropdown item hover/current bg (was: none) |
+| `$skinMenuItemHoverTextColor` | `#6cb0de` | hover/current dropdown item text, same reason |
+| `$skinMenuFontSize` | `13px` | header menu text size |
+| `$skinMenuItemPaddingY` | `5px` | dropdown item top/bottom padding (was 6px/4px + a 7px border) |
+| `$skinMenuItemLineHeight` | `1.35` | dropdown item line-height |
+| `$skinMenuPanelMaxWidth` | `260px` | dropdown panel ceiling; longer labels wrap instead of leaving the viewport |
+| `$skinHeaderPaddingY` | `null` | sets both halves at once |
+| `$skinHeaderPaddingTop` | `4.5px` | header top padding (base value, kept so the header does not shift) |
+| `$skinHeaderPaddingBottom` | `4.5px` | header bottom padding |
+| `$skinHeaderLogoMaxHeight` | `none` | cap the site_title logo image height |
+
+#### Title bar
+
+| Variable | Default (light / dark) | |
+|---|---|---|
+| `$skinTitleBarColor` | `#343c46` |  |
+| `$skinTitleBarBorderColor` | `$skinMainSecondColor` |  |
+| `$skinTitleBarBorderWidth` | `0` |  |
+| `$skinTitleBarButtonPaddingY` | `6px` | action button vertical padding |
+| `$skinTitleBarButtonPaddingX` | `10px` | action button horizontal padding |
+
+#### Panels, tabs and labels
+
+| Variable | Default (light / dark) | |
+|---|---|---|
+| `$skinPanelHeaderColor` / `$skinPanelHeaderColorDark` | `var(--aa-page-bg)` / `var(--aa-page-bg)` |  |
+| `$skinPanelHeaderTextColor` / `$skinPanelHeaderTextColorDark` | `var(--aa-inactive-tab-text)` / `var(--aa-inactive-tab-text)` |  |
+| `$skinPanelHeaderPaddingY` | `5px` | panel + sidebar header height |
+| `$skinLabelColor` / `$skinLabelColorDark` | `#8494a8` / `$skinTextColorDark` |  |
+| `$skinTabInactiveColor` / `$skinTabInactiveColorDark` | `#f7f9fb` / `#161a1e` | inactive tab fill |
+| `$skinActiveTabTextColor` / `$skinActiveTabTextColorDark` | `$skinMainSecondColor` / `#7cc0ec` | selected tab label |
+| `$skinInactiveTabTextColor` / `$skinInactiveTabTextColorDark` | `#5e6469` / `#b0b8c2` | inactive tab label |
+| `$skinTableHeaderTextColor` / `$skinTableHeaderTextColorDark` | `#5e6469` / `#dde2e8` | index-table column header text |
+| `$skinTabPaddingY` | `8px` | tab height |
+| `$skinTabPaddingX` | `15px` | tab label horizontal padding (text → border) |
+
+#### Buttons and table tools
+
+| Variable | Default (light / dark) | |
+|---|---|---|
+| `$skinButtonColor` / `$skinButtonColorDark` | `darken($skinMainSecondColor, 20%)` / `$skinButtonColor` | one tone in both modes; white on it is 5.35:1 |
+| `$skinButtonTextColor` / `$skinButtonTextColorDark` | `#ffffff` / `$skinButtonTextColor` | label on those buttons |
+| `$skinTableToolsHeight` | `30px` |  |
+| `$skinTableToolsPaddingX` | `$skinTableToolsHeight * 0.4` | 12px at 30px |
+
+#### Links
+
+| Variable | Default (light / dark) | |
+|---|---|---|
+| `$skinAccentColor` / `$skinAccentColorDark` | `$skinMainSecondColor` / `$skinAccentColor` | focus ring / accent outline |
+| `$skinLinkColor` / `$skinLinkColorDark` | `#38678b` / `#7cc0ec` |  |
+| `$skinDeleteLinkColor` / `$skinDeleteLinkColorDark` | `$skinLinkColor` / `#f49b9b` |  |
+
 ## Screen
 
-<a href="./img/wigu.png"><img src="./img/wigu.png"></a>
+Index with filters, show page, nested `has_many` form, an open batch-actions
+menu and the datepicker — the same admin in both modes. The theme follows the
+operating system and can be pinned per page with `data-theme`.
+
+#### Light
+
+[![Light](./img/light.png)](./img/light.png)
+
+#### Dark
+
+[![Dark](./img/dark.png)](./img/dark.png)
+
+#### Form and filter controls
+
+Shown at full size, because the two shots above scale the controls down past
+the point where you can tell what colour they are. Inputs, selects and
+textareas take `$skinInputBgColor` / `$skinInputBorderColor` — white on
+`#c9ced4` in light mode, a recessed `#1e2227` well on `#4d555f` in dark — and
+the focused field (`Name`, `Title`) carries `$skinMainSecondColor`.
 
+[![Form and filter inputs](./img/inputs.png)](./img/inputs.png)
 
 ## Contributing
 

data/app/assets/javascripts/wigu/theme_toggle.js

@@ -0,0 +1,140 @@
+// Theme switch for active_admin_theme. Optional — the stylesheet works without
+// it, following the operating system.
+//
+// Cycles auto -> light -> dark -> auto:
+//   auto        no stored choice; follows prefers-color-scheme, live
+//   light/dark  pins html[data-theme] and remembers it
+//
+// The only thing this writes to the page is data-mode on the control; the
+// stylesheet draws the icon from it. That keeps appearance in the theme, where
+// a project can restyle it, instead of in a script it would have to fork.
+//
+// Binds by delegation to anything carrying .dark-mode-toggle or #theme_toggle,
+// so the control can live anywhere and survive a re-render. If neither exists
+// it inserts its own entry into the utility navigation. No jQuery and no ujs,
+// so it does not care how the admin is built.
+(function () {
+  "use strict";
+
+  var KEY = "aa-theme";
+  var ORDER = { auto: "light", light: "dark", dark: "auto" };
+  var LABEL = {
+    auto: "Theme: auto (follows the system) — click for light",
+    light: "Theme: light — click for dark",
+    dark: "Theme: dark — click for auto",
+  };
+  var root = document.documentElement;
+
+  // localStorage throws in private mode in some browsers, and is absent in a few
+  // embedded webviews. Losing the preference is acceptable; breaking the admin
+  // is not.
+  function stored() {
+    try { return localStorage.getItem(KEY); } catch (e) { return null; }
+  }
+  function store(value) {
+    try { value === null ? localStorage.removeItem(KEY) : localStorage.setItem(KEY, value); } catch (e) {}
+  }
+
+  // The choice is held here and storage is best-effort persistence. Reading it
+  // back instead would make the switch a no-op wherever localStorage throws —
+  // private mode in some browsers — because the write is swallowed and the next
+  // read returns the old value.
+  var current = null;
+
+  function mode() {
+    if (current === null) current = normalise(stored());
+    return current;
+  }
+
+  function normalise(value) {
+    return value === "light" || value === "dark" ? value : "auto";
+  }
+
+  function apply() {
+    // auto drops the attribute entirely so the media query decides.
+    if (mode() === "auto") root.removeAttribute("data-theme");
+    else root.setAttribute("data-theme", mode());
+  }
+
+  // Before DOMContentLoaded on purpose: applied later, the page paints in the
+  // other theme first and flashes.
+  apply();
+
+  function ready(fn) {
+    if (document.readyState !== "loading") fn();
+    else document.addEventListener("DOMContentLoaded", fn);
+  }
+
+  var SELECTOR = ".dark-mode-toggle, #theme_toggle";
+
+  function controls() {
+    return document.querySelectorAll(SELECTOR);
+  }
+
+  function refresh() {
+    var active = mode();
+    Array.prototype.forEach.call(controls(), function (host) {
+      // The host itself may be the anchor (a menu item) or wrap one (our own li).
+      var link = host.tagName === "A" ? host : host.querySelector("a") || host;
+      host.setAttribute("data-mode", active);
+      link.setAttribute("title", LABEL[active]);
+      link.setAttribute("aria-label", LABEL[active]);
+    });
+  }
+
+  function cycle() {
+    var next = ORDER[mode()];
+    current = next;
+    store(next === "auto" ? null : next);
+    apply();
+    refresh();
+  }
+
+  // Delegated, so a control added later — or replaced by a Turbo render — still
+  // works without rebinding.
+  document.addEventListener("click", function (event) {
+    if (!event.target.closest || !event.target.closest(SELECTOR)) return;
+    event.preventDefault();
+    cycle();
+  });
+
+  // The control is a link with no destination, so it is reachable by Tab; that
+  // makes Enter and Space its keyboard contract.
+  document.addEventListener("keydown", function (event) {
+    if (event.key !== "Enter" && event.key !== " ") return;
+    if (!event.target.closest || !event.target.closest(SELECTOR)) return;
+    event.preventDefault();
+    cycle();
+  });
+
+  // Another tab changed the preference.
+  window.addEventListener("storage", function (event) {
+    if (event.key !== KEY) return;
+    current = normalise(event.newValue);
+    apply();
+    refresh();
+  });
+
+  // In auto mode, follow the operating system while the page is open.
+  if (window.matchMedia) {
+    var query = window.matchMedia("(prefers-color-scheme: dark)");
+    var onChange = function () { if (mode() === "auto") { apply(); refresh(); } };
+    if (query.addEventListener) query.addEventListener("change", onChange);
+    else if (query.addListener) query.addListener(onChange);
+  }
+
+  ready(function () {
+    if (controls().length === 0) {
+      var nav = document.getElementById("utility_nav");
+      if (!nav) return;
+      var host = document.createElement("li");
+      host.id = "theme_toggle";
+      var link = host.appendChild(document.createElement("a"));
+      // Not "#": ActiveAdmin treats a bare hash as a blank menu item.
+      link.setAttribute("href", "#theme");
+      link.setAttribute("role", "button");
+      nav.insertBefore(host, nav.firstChild);
+    }
+    refresh();
+  });
+})();