super_settings 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5417df66afb91b92e9142075a083883d6884a5f148858b43738cafb4bbe5aea3
-  data.tar.gz: 7156046f2de10818424ff1997a1aea922ea5c67ebea1c0fe2ce8ffbb5f8a9746
+  metadata.gz: 3c33c68388f12bb6216f928e778f5a4965bf11f263bc315f0a9ce9261f9d4637
+  data.tar.gz: fc7e9bd62a5412843c0da1a2accf93812869ae85cf91c8b7accd0eb496c9cf00
 SHA512:
-  metadata.gz: a8fd1761f7cf0eeee7b30d06ea1dc7b766dde492c3b8786fb549469ee76e1d81321696ea1d8bef1a272896be6992ab5af598cf521e4c91090602f5fe809de146
-  data.tar.gz: fc346701a55ad717e806d234780df064aebe15d981e1e5da65c4d435bcb6b8b13d6b5ac240d654e827e167ebd083dbb8e4319831bb7aa09aba94b44ac27b8f7f
+  metadata.gz: d85f6b31e1757e36fbfe6486851ee2ccfdf10b13bca742ed90910898761c2215ca053ee2a91ad204b65913d765b66084b03e802544985c3d3c263d692c54480d
+  data.tar.gz: 17a61ebac8696d0d2b1ca09229b0826d8885853e858f3ebcb2956cad00d56cf35f9e0928afc4c4e0987d270be3b9b23ab52cf18c91c91874281e3ac2239e81ad

data/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.6.0
+
+### Added
+
+- Added `SuperSettings::Application#dark_mode_selector` configuration option that allows you to specify a CSS selector that sets dark mode when it matches an element in the page. This is an alternative to using the `color_scheme` option and allows for more flexible control of when dark mode is enabled.
+
 ## 2.5.0
 
 ### Added

data/README.md

@@ -308,6 +308,13 @@ SuperSettings.configure do |config|
   # Set the color scheme to use for the Web UI. Options are :light (default), :dark, or :system.
   config.controller.color_scheme = :dark
 
+  # Set a CSS selector for enabling dark mode. When the selector matches an element on the page,
+  # dark mode styles will be applied. A theme toggle button will also be rendered in the header
+  # allowing users to switch between light and dark modes (persisted via localStorage).
+  # This is an alternative to the color_scheme option. If neither color_scheme nor dark_mode_selector
+  # is set, it defaults to "[data-theme=dark]" which enables the toggle automatically.
+  config.controller.dark_mode_selector = "[data-theme=dark]"
+
   # Add additional code to the controller. In this case we are adding code to ensure only
   # admins can access the functionality and changing the layout to use one defined by the application.
   config.controller.enhance do
@@ -464,12 +471,6 @@ This will work out of the box with the defaults for the storage engines when run
 - `S3_URL` - `s3://accesskey:secretkey@region-1/settings/settings.json` (the S3 endpoint will be set to `http://localhost:9000`)
 - `MONGODB_URL` - `mongodb://localhost:27017/super_settings`
 
-Finally, you can run the application in dark mode by setting the `COLOR_SCHEME` environment variable.
-
-```bash
-COLOR_SCHEME=dark bundle exec rackup
-```
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/VERSION

@@ -1 +1 @@
-2.5.0
+2.6.0

data/app/helpers/super_settings/settings_helper.rb

@@ -29,6 +29,7 @@ module SuperSettings
       application_dir = File.expand_path(File.join("..", "..", "..", "lib", "super_settings", "application"), __dir__)
       erb = ERB.new(File.read(File.join(application_dir, "layout_vars.css.erb")))
       color_scheme = SuperSettings.configuration.controller.color_scheme
+      dark_mode_selector = SuperSettings.configuration.controller.dark_mode_selector
       erb.result(binding).html_safe
     end
   end

data/lib/super_settings/application/helper.rb

@@ -222,6 +222,14 @@ module SuperSettings
       @color_scheme if defined?(@color_scheme)
     end
 
+    # A CSS selector that sets dark mode when it matches an element in the page.
+    # This is an alternative to using the color_scheme option.
+    #
+    # @return [String, nil]
+    def dark_mode_selector
+      @dark_mode_selector if defined?(@dark_mode_selector)
+    end
+
     # Whether the application is in read-only mode.
     #
     # @return [Boolean]

data/lib/super_settings/application/layout.html.erb

@@ -8,6 +8,18 @@
     <meta name="format-detection" content="telephone=no email=no date=no address=no">
     <meta name="robots" content="noindex, nofollow">
     <meta name="referrer" content="no-referrer-when-downgrade">
+    <% if dark_mode_selector %>
+    <script>
+      (function() {
+        try {
+          if (localStorage.getItem("super_settings_theme") === "dark") {
+            document.documentElement.setAttribute("data-theme", "dark");
+          }
+        } catch (e) {
+        }
+      })();
+    </script>
+    <% end %>
     <%= layout_style_tag %>
     <%= add_to_head %>
   </head>
@@ -16,6 +28,24 @@
     <header class="super-settings-page-header">
       <div class="super-settings-page-header-inner">
         <%= application_header %>
+        <% if dark_mode_selector %>
+        <button type="button" class="super-settings-theme-toggle" id="super-settings-theme-toggle" aria-label="Toggle dark mode">
+          <svg class="super-settings-theme-icon super-settings-theme-icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="12" cy="12" r="4"></circle>
+            <path d="M12 2v2"></path>
+            <path d="M12 20v2"></path>
+            <path d="m4.93 4.93 1.41 1.41"></path>
+            <path d="m17.66 17.66 1.41 1.41"></path>
+            <path d="M2 12h2"></path>
+            <path d="M20 12h2"></path>
+            <path d="m6.34 17.66-1.41 1.41"></path>
+            <path d="m19.07 4.93-1.41 1.41"></path>
+          </svg>
+          <svg class="super-settings-theme-icon super-settings-theme-icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"></path>
+          </svg>
+        </button>
+        <% end %>
       </div>
     </header>
 
@@ -72,5 +102,31 @@
         </details>
       </footer>
     <% end %>
+    <% if dark_mode_selector %>
+    <script>
+      (function() {
+        var toggle = document.getElementById("super-settings-theme-toggle");
+        if (!toggle) return;
+
+        var html = document.documentElement;
+        toggle.addEventListener("click", function() {
+          var isDark = html.getAttribute("data-theme") === "dark";
+          if (isDark) {
+            html.removeAttribute("data-theme");
+            try {
+              localStorage.removeItem("super_settings_theme");
+            } catch (e) {
+            }
+          } else {
+            html.setAttribute("data-theme", "dark");
+            try {
+              localStorage.setItem("super_settings_theme", "dark");
+            } catch (e) {
+            }
+          }
+        });
+      })();
+    </script>
+    <% end %>
   </body>
 </html>

data/lib/super_settings/application/layout_styles.css

@@ -112,6 +112,43 @@ a:visited {
   justify-content: flex-end;
 }
 
+.super-settings-theme-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  background: transparent;
+  color: #9ca3af;
+  cursor: pointer;
+  flex-shrink: 0;
+  transition: color 0.2s, border-color 0.2s;
+}
+
+.super-settings-theme-toggle:hover {
+  color: var(--link-color);
+  border-color: var(--link-color);
+}
+
+.super-settings-theme-icon {
+  width: 18px;
+  height: 18px;
+}
+
+.super-settings-theme-icon-moon {
+  display: none;
+}
+
+[data-theme="dark"] .super-settings-theme-icon-sun {
+  display: none;
+}
+
+[data-theme="dark"] .super-settings-theme-icon-moon {
+  display: block;
+}
+
 /* ══════════════════════════════════════════
    LANGUAGE MENU (in footer)
    ══════════════════════════════════════════ */

data/lib/super_settings/application/layout_vars.css.erb

@@ -13,7 +13,11 @@
 <% end %>
 <% if color_scheme == :system || color_scheme == :dark %>
   :root {
-    --text-color: #e5e7eb;
+<% elsif dark_mode_selector %>
+  :root<%= dark_mode_selector %> {
+<% end %>
+<% if color_scheme == :system || color_scheme == :dark || dark_mode_selector %>
+    --text-color: #eef0f8;
     --background-color: #1a1d23;
     --header-background-color: #21252b;
     --link-color: #2dd4bf;

data/lib/super_settings/application/style_vars.css.erb

@@ -71,8 +71,10 @@
 
 <% if color_scheme == :system %>
   @media (prefers-color-scheme: dark) {
+<% elsif dark_mode_selector %>
+  <%= dark_mode_selector %> {
 <% end %>
-<% if color_scheme == :system || color_scheme == :dark %>
+<% if color_scheme == :system || color_scheme == :dark || dark_mode_selector %>
   .super-settings {
     /* Canvas */
     --bg-page: #1a1d23;
@@ -128,6 +130,6 @@
     --icon-disabled-color: #4b5563;
   }
 <% end %>
-<% if color_scheme == :system %>
+<% if color_scheme == :system || dark_mode_selector %>
   }
 <% end %>

data/lib/super_settings/application.rb

@@ -8,14 +8,16 @@ module SuperSettings
     include Helper
 
     # @param layout [String, Symbol] path to an ERB template to use as the layout around the application UI. You can
-    #                                pass the symbol +:default+ to use the default layout that ships with the gem.
+    #   pass the symbol +:default+ to use the default layout that ships with the gem.
     # @param add_to_head [String] HTML code to add to the <head> element on the page.
     # @param api_base_url [String] the base URL for the REST API.
     # @param color_scheme [Symbol] whether to use dark mode for the application UI. If +nil+, the user's system
-    #                              preference will be used.
+    #   preference will be used.
+    # @param dark_mode_selector [String] a CSS selector that sets dark mode when it matches an element in the page.
+    #   This is an alternative to using the color_scheme option.
     # @param read_only [Boolean] whether to render the application in read-only mode (edit controls hidden).
     # @param locale [String] the locale code for translations (default: "en").
-    def initialize(layout: nil, add_to_head: nil, api_base_url: nil, color_scheme: nil, read_only: false, locale: nil)
+    def initialize(layout: nil, add_to_head: nil, api_base_url: nil, color_scheme: nil, dark_mode_selector: nil, read_only: false, locale: nil)
       if layout
         layout = File.expand_path(File.join("application", "layout.html.erb"), __dir__) if layout == :default
         @layout = ERB.new(File.read(layout)) if layout
@@ -27,6 +29,7 @@ module SuperSettings
 
       @api_base_url = api_base_url
       @color_scheme = color_scheme&.to_sym
+      @dark_mode_selector = dark_mode_selector
       @read_only = !!read_only
       @locale = locale || SuperSettings::MiniI18n::DEFAULT_LOCALE
     end

data/lib/super_settings/configuration.rb

@@ -12,6 +12,8 @@ module SuperSettings
 
     # Configuration for the controller.
     class Controller
+      VALID_COLOR_SCHEMES = [:light, :dark, :system].freeze
+
       # @api private
       attr_reader :enhancement
 
@@ -25,12 +27,13 @@ module SuperSettings
       def initialize
         @superclass = nil
         @web_ui_enabled = true
-        @color_scheme = false
+        @color_scheme = nil
         @changed_by_block = nil
         @enhancement = nil
         @application_name = nil
         @application_logo = nil
         @application_link = nil
+        @dark_mode_selector = nil
       end
 
       def superclass
@@ -41,10 +44,10 @@ module SuperSettings
         end
       end
 
-      # Optinal name of the application displayed in the view.
+      # Optional name of the application displayed in the view.
       attr_accessor :application_name
 
-      # Optional mage URL for the application logo.
+      # Optional image URL for the application logo.
       attr_accessor :application_logo
 
       # Optional URL for a link back to the rest of the application.
@@ -69,11 +72,30 @@ module SuperSettings
       end
 
       # Set dark mode for the web UI. Possible values are :light, :dark, or :system.
-      # The default value is :light.
+      # When the value is not set (or is invalid), theme selection is left dynamic.
       attr_writer :color_scheme
 
+      # Return the configured color scheme.
+      #
+      # @return [Symbol, nil]
       def color_scheme
-        (@color_scheme ||= :light).to_sym
+        scheme = @color_scheme&.to_sym
+        VALID_COLOR_SCHEMES.include?(scheme) ? scheme : nil
+      end
+
+      # Set a CSS selector that sets dark mode. This is an alternative to using the color_scheme
+      # option and can be used if you have a custom implementation for dark mode in your application.
+      # Dark mode will be enabled in the settings web UI when the selector matches an element in the page.
+      attr_accessor :dark_mode_selector
+
+      # Return the selector used to enable dark mode from host page state.
+      #
+      # @return [String, nil]
+      def resolved_dark_mode_selector
+        return @dark_mode_selector if @dark_mode_selector
+        return "[data-theme=dark]" if color_scheme.nil?
+
+        nil
       end
 
       # Enhance the controller. You can define methods or call controller class methods like

data/lib/super_settings/controller_actions.rb

@@ -19,8 +19,13 @@ module SuperSettings
 
     # Render the HTML application for managing settings.
     def root
-      html = SuperSettings::Application.new(read_only: super_settings_read_only?, locale: I18n.locale).render
-      render html: html.html_safe, layout: true
+      application = SuperSettings::Application.new(
+        read_only: super_settings_read_only?,
+        locale: I18n.locale,
+        color_scheme: SuperSettings.configuration.controller.color_scheme,
+        dark_mode_selector: SuperSettings.configuration.controller.resolved_dark_mode_selector
+      )
+      render html: application.render.html_safe, layout: true
     end
 
     # API endpoint for getting active settings. See SuperSettings::RestAPI for details.

data/lib/super_settings/rack_application.rb

@@ -104,9 +104,9 @@ module SuperSettings
     # Subclasses can override this method to return the path to an ERB file to use as the layout
     # for the HTML application. The layout can use any of the methods defined in SuperSettings::Application::Helper.
     #
-    # @return [String]
+    # @return [String, Symbol]
     def layout
-      "layout.html.erb"
+      :default
     end
 
     # Subclasses can override this method to add custom HTML to the <head> element in the HTML application.
@@ -186,7 +186,15 @@ module SuperSettings
         if lang && SuperSettings::MiniI18n.available_locales.include?(lang)
           headers["set-cookie"] = "super_settings_locale=#{lang}; path=/; SameSite=Lax"
         end
-        [200, headers, [Application.new(layout: :default, add_to_head: add_to_head(request), color_scheme: SuperSettings.configuration.controller.color_scheme, read_only: read_only, locale: locale).render]]
+        application = Application.new(
+          layout: layout,
+          add_to_head: add_to_head(request),
+          color_scheme: SuperSettings.configuration.controller.color_scheme,
+          dark_mode_selector: SuperSettings.configuration.controller.resolved_dark_mode_selector,
+          read_only: read_only,
+          locale: locale
+        )
+        [200, headers, [application.render]]
       end
 
       if [401, 403].include?(response.first)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: super_settings
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Brian Durand