ultra_settings 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f70521135220d74fe5ef4fbc6261c9d5b8a93f200f898af0fead2ebb7d31cbfd
-  data.tar.gz: 42330a1a294bee7ab53c61f37b56cd0b5b6f309326f1809bfd012cbfcd67fa58
+  metadata.gz: 846f2c54ef9d4019e4f97ad02dcc962813a29fccc6128fe1e18ef9f263c01c2e
+  data.tar.gz: 7d28f71ae610362fd8e2c4e0ffe2ae885d7b9f270fc0e942f41fd7e8daff18fc
 SHA512:
-  metadata.gz: aab2c06121a67e227f1628d1dd3a22590e0bb174f132506840112278a5c09484e57dd6bc176ddbb35d576388c29bb5f6da462473f1c5ebf76724fe8677312ed2
-  data.tar.gz: f7e9bd08a2958def30780e0ef966d8b90321d3f9c1bf469677b7c51ab8b512e867bf0e1fc1d910d72f24c9f71818a34050b3a2dbfdc2c5adb9afa4a3e048948a
+  metadata.gz: 8829e070b1f37474fc6673804d219d1485b2cb36c5d81f9dcd4b88ff6623bd1f99a5a135adedf4cc2a2f1865ac27d74b8f405b01896aabc3da2b5e41226333f3
+  data.tar.gz: 0e906fddfea5764d653beb41c99d534c30b44974a83b8f7e3de1d76dd1656e367fe160743f4ac65ec422bf0e1c7d0c35b28ff2d5e3ce4252bf70d53d0f367709

data/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.8.0
+
+### Added
+
+- Added support for setting a description on configuration classes. The class description can serve to document the purpose of the configuration and will be shown in the web UI.
+- Improved menu for selecting configuration classes in the web UI by adding a search box to filter the list of configurations.
+
+### Fixed
+
+- Fixed filtering of data sources for configuration classes in the web UI.
+  - The YAML source will not be shown if the configuration file is set to nil or false.
+  - The runtime settings source will not be shown if the runtime settings engine is not set up.
+  - Fields that override the class default for a data source will now correctly show that source.
+
 ## 2.7.0
 
 ### Added

data/README.md

@@ -424,7 +424,7 @@ If you prefer to embed the settings view directly into your own admin tools or d
 ```erb
 <h1>Configuration</h1>
 
-<%= UltraSettings::ApplicationView.new.render(select_class: "form-select") %>
+<%= UltraSettings::ApplicationView.new.render %>
 ```
 
 This approach allows for seamless integration of the settings UI into your application's admin interface, leveraging your existing authentication and authorization mechanisms. The settings are rendered with navigation handled by an HTML select element. You can specify the CSS classes for the select element to match your own application styles..

data/VERSION

@@ -1 +1 @@
-2.7.0
+2.8.0

data/app/_config_description.html.erb

@@ -0,0 +1,30 @@
+<% config_class = configuration.class
+  has_config_file = config_class.configuration_file.is_a?(Pathname) && config_class.fields.any?(&:yaml_key) %>
+
+<% if config_class.description || has_config_file %>
+  <div class="ultra-settings-description-container">
+    <% if config_class.description %>
+      <div class="ultra-settings-description">
+        <%= html_escape(config_class.description).gsub("\n", "<br>") %>
+      </div>
+    <% end %>
+
+    <% if has_config_file %>
+      <div class="ultra-settings-description">
+        <span class="ultra-settings-config-file-label">
+          Configuration file:
+        </span>
+
+        <code class="ultra-settings-config-file-path">
+          <%= html_escape(relative_path(configuration.class.configuration_file)) %>
+        </code>
+
+        <% unless configuration.class.configuration_file&.exist? %>
+          <span class="ultra-settings-file-not-found">
+            (file does not exist)
+          </span>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+<% end %>

data/app/_config_list.html.erb

@@ -0,0 +1,14 @@
+<div class="ultra-settings-configuration-list" style="display:none;">
+  <% configurations.each do |configuration| %>
+    <div class="ultra-settings-configuration-summary">
+      <a
+        href="#<%= html_escape(configuration.class.name) %>"
+        class="ultra-settings-configuration-title"
+      >
+        <%= html_escape(configuration.class.name) %>
+      </a>
+
+      <p><%= html_escape(configuration.class.description) %></p>
+    </div>
+  <% end %>
+</div>

data/app/_select_menu.html.erb

@@ -0,0 +1,53 @@
+<div class="ultra-settings-dropdown" id="config-dropdown">
+  <button
+    type="button"
+    class="ultra-settings-dropdown-button"
+    id="config-dropdown-button"
+  >
+    Select Configuration
+  </button>
+
+  <div
+    class="ultra-settings-dropdown-menu"
+    id="config-dropdown-menu"
+    style="display: none;"
+  >
+    <div class="ultra-settings-search-container">
+      <input
+        type="text"
+        id="config-search"
+        placeholder="Search..."
+        autocomplete="off"
+      >
+    </div>
+
+    <ul class="ultra-settings-dropdown-list" id="config-list">
+      <% configurations.each do |config| %>
+        <% config_text = [
+            config.class.name,
+            config.class.description
+          ]
+          config.class.fields.each do |field|
+            config_text << field.name
+            config_text << field.description
+            config_text << field.env_var
+            config_text << field.runtime_setting
+          end
+          search_text = config_text.compact.join(" ").downcase %>
+
+        <li
+          class="ultra-settings-dropdown-item"
+          data-value="config-<%= html_escape(config.class.name) %>"
+          data-label="<%= html_escape(config.class.name) %>"
+          data-search="<%= html_escape(search_text) %>"
+        >
+          <span class="ultra-settings-check-icon"></span>
+
+          <span class="ultra-settings-config-name">
+            <%= html_escape(config.class.name) %>
+          </span>
+        </li>
+      <% end %>
+    </ul>
+  </div>
+</div>

data/app/application.css

@@ -2,22 +2,22 @@
   margin-bottom: 1rem;
 }
 
-.ultra-settings-nav form {
-  margin: 0;
-}
-
-.ultra-settings-config-file {
+.ultra-settings-description-container {
   margin-bottom: 1.5rem;
-  padding: 1rem;
-  background-color: var(--config-file-bg-color);
+  line-height: 1.5;
   border: 1px solid var(--config-file-border-color);
   border-radius: 0.375rem;
+  padding: 1rem 1rem 0 1rem;
+}
+
+.ultra-settings-description {
+  margin-bottom: 1rem;
+  color: var(--description-color);
 }
 
 .ultra-settings-config-file-label {
-  font-weight: 600;
-  color: var(--text-color);
-  margin-right: 0.5rem;
+  font-weight: 500;
+  color: var(--description-color);
 }
 
 .ultra-settings-config-file-path {
@@ -184,9 +184,9 @@ code.ultra-settings-field-data-value {
   letter-spacing: 0.025em;
 }
 
-.ultra-settings-source-value-dfn {
-  display: inline-block;
-  margin-left: 0.25rem;
+.ultra-settings-source-indicator::before {
+  content: "● ";
+  font-size: 1rem;
 }
 
 .ultra-settings-icon-info {
@@ -218,27 +218,6 @@ code.ultra-settings-field-data-value {
   opacity: 1;
 }
 
-.ultra-settings-select {
-  display: inline-block;
-  padding: .375rem 2.25rem .375rem .75rem;
-  -moz-padding-start: calc(0.75rem - 3px);
-  font-size: 1rem;
-  font-weight: 400;
-  line-height: 1.5;
-  color: var(--form-control-color);
-  background-color: var(--form-control-bg-color);
-  background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23343a40' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M2 5l6 6 6-6'/%3e%3c/svg%3e");
-  background-repeat: no-repeat;
-  background-position: right .75rem center;
-  background-size: 16px 12px;
-  border: 1px solid var(--form-control-border-color);
-  border-radius: .25rem;
-  transition: border-color .15s ease-in-out,box-shadow .15s ease-in-out;
-  -webkit-appearance: none;
-  -moz-appearance: none;
-  appearance: none;
-}
-
 .ultra-settings-dialog {
   min-width: 20rem;
   padding: 0;
@@ -273,4 +252,163 @@ code.ultra-settings-field-data-value {
   padding: 1rem;
   background-color: var(--background-color);
   color: var(--text-color);
+}
+
+/* Dropdown Styles */
+.ultra-settings-dropdown {
+  position: relative;
+  display: inline-block;
+  width: 100%;
+  max-width: 400px;
+}
+
+.ultra-settings-dropdown-button {
+  width: 100%;
+  text-align: left;
+  padding: 0.5rem 1rem;
+  font-size: 1.25rem;
+  font-weight: 500;
+  background-color: var(--form-control-bg-color);
+  color: var(--form-control-color);
+  border: 1px solid var(--form-control-border-color);
+  border-radius: 0.375rem;
+  cursor: pointer;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.ultra-settings-dropdown-button::after {
+  content: "";
+  display: inline-block;
+  width: 0;
+  height: 0;
+  margin-left: 0.5rem;
+  vertical-align: middle;
+  border-top: 4px solid;
+  border-right: 4px solid transparent;
+  border-left: 4px solid transparent;
+}
+
+.ultra-settings-dropdown-menu {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  z-index: 1000;
+  display: none;
+  min-width: 100%;
+  padding: 0.5rem 0;
+  margin: 0.125rem 0 0;
+  font-size: 1rem;
+  color: var(--text-color);
+  text-align: left;
+  list-style: none;
+  background-color: var(--form-control-bg-color);
+  background-clip: padding-box;
+  border: 1px solid var(--form-control-border-color);
+  border-radius: 0.375rem;
+  box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
+}
+
+.ultra-settings-search-container {
+  padding: 0.5rem 1rem;
+  border-bottom: 1px solid var(--form-control-border-color);
+}
+
+#config-search {
+  width: 100%;
+  padding: 0.375rem 0.75rem;
+  font-size: 0.875rem;
+  line-height: 1.5;
+  color: var(--form-control-color);
+  background-color: var(--value-bg-color);
+  background-clip: padding-box;
+  border: 1px solid var(--form-control-border-color);
+  border-radius: 0.25rem;
+  box-sizing: border-box;
+}
+
+.ultra-settings-dropdown-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  max-height: 300px;
+  overflow-y: auto;
+}
+
+.ultra-settings-dropdown-item {
+  display: flex;
+  align-items: center;
+  padding: 0.5rem 1rem;
+  clear: both;
+  font-weight: 400;
+  color: var(--form-control-color);
+  text-align: inherit;
+  white-space: nowrap;
+  background-color: transparent;
+  border: 0;
+  cursor: pointer;
+}
+
+.ultra-settings-dropdown-item:hover {
+  background-color: var(--field-header-bg-color);
+}
+
+.ultra-settings-check-icon {
+  width: 1.5rem;
+  display: inline-block;
+  text-align: center;
+  font-weight: bold;
+}
+
+.ultra-settings-dropdown-item.selected .ultra-settings-check-icon::before {
+  content: "✓";
+}
+
+.ultra-settings-title {
+  margin: 0;
+  font-size: 1.25rem;
+  font-weight: 500;
+  color: var(--text-color);
+}
+
+/* Configuration List Styles */
+.ultra-settings-configuration-list {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(max(300px, 30%), 1fr));
+  gap: 1.5rem;
+  margin-top: 1.5rem;
+}
+
+.ultra-settings-configuration-summary {
+  background-color: var(--field-bg-color);
+  border: 1px solid var(--field-border-color);
+  border-radius: 0.5rem;
+  padding: 1.5rem;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+  overflow: hidden;
+}
+
+.ultra-settings-configuration-summary:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.1);
+}
+
+.ultra-settings-configuration-title {
+  display: block;
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: var(--description-color);
+  text-decoration: none;
+  margin-bottom: 0.75rem;
+}
+
+.ultra-settings-configuration-title:hover {
+  text-decoration: underline;
+}
+
+.ultra-settings-configuration-summary p {
+  margin: 0;
+  color: var(--description-color);
+  line-height: 1.5;
 }

data/app/application.js

@@ -1,41 +1,124 @@
 document.addEventListener("DOMContentLoaded", () => {
-  const menu = document.getElementById("config-selector");
+  const dropdown = document.getElementById("config-dropdown");
+  const button = document.getElementById("config-dropdown-button");
+  const menu = document.getElementById("config-dropdown-menu");
+  const searchInput = document.getElementById("config-search");
+  const items = document.querySelectorAll(".ultra-settings-dropdown-item");
+  const configurations = document.querySelectorAll(".ultra-settings-configuration");
+  const configList = document.querySelector(".ultra-settings-configuration-list");
 
-  showCurrentConfiguration = () => {
-    const selectedId = menu.options[menu.selectedIndex].value;
-    const hash = selectedId.replace(/^config-/, "");
+  // If no dropdown, we might be in single config mode or no configs.
+  if (!dropdown) {
+    // If there is exactly one configuration, show it.
+    if (configurations.length === 1) {
+      configurations[0].style.display = "block";
+    }
+    return;
+  }
 
-    document.querySelectorAll(".ultra-settings-configuration").forEach((configuration) => {
-      if (configuration.id === selectedId) {
-        configuration.style.display = "block";
-        window.location.hash = hash;
+  const toggleMenu = () => {
+    const isVisible = menu.style.display === "block";
+    menu.style.display = isVisible ? "none" : "block";
+    if (!isVisible) {
+      searchInput.value = "";
+      filterItems("");
+      searchInput.focus();
+    }
+  };
+
+  const closeMenu = () => {
+    menu.style.display = "none";
+  };
+
+  const filterItems = (query) => {
+    const lowerQuery = query.toLowerCase();
+    items.forEach(item => {
+      const label = item.getAttribute("data-search").toLowerCase();
+      if (label.includes(lowerQuery)) {
+        item.style.display = "flex";
       } else {
-        configuration.style.display = "none";
+        item.style.display = "none";
       }
     });
-  }
+  };
 
-  menu.addEventListener("change", showCurrentConfiguration);
+  const showConfigList = () => {
+    if (configList) configList.style.display = "grid";
+    configurations.forEach(config => config.style.display = "none");
+    items.forEach(item => item.classList.remove("selected"));
+    button.textContent = "Select Configuration";
+    closeMenu();
+  };
 
-  const setCurrentSelection =  () => {
-    const hash = window.location.hash.replace(/^#/, "");
-    const selectedId = `config-${hash}`;
-    for (const option of menu.options) {
-      if (option.value === selectedId) {
-        option.selected = true;
-        break;
+  const showConfig = (configId) => {
+    if (configList) configList.style.display = "none";
+
+    configurations.forEach(config => {
+      config.style.display = config.id === configId ? "block" : "none";
+    });
+
+    items.forEach(item => {
+      if (item.getAttribute("data-value") === configId) {
+        item.classList.add("selected");
+        button.textContent = item.getAttribute("data-label");
+      } else {
+        item.classList.remove("selected");
       }
+    });
+
+    closeMenu();
+  };
+
+  // Event Listeners
+  button.addEventListener("click", (e) => {
+    e.stopPropagation();
+    toggleMenu();
+  });
+
+  document.addEventListener("click", (e) => {
+    if (!dropdown.contains(e.target)) {
+      closeMenu();
     }
+  });
 
-    showCurrentConfiguration();
-  }
+  searchInput.addEventListener("input", (e) => {
+    filterItems(e.target.value);
+  });
 
-  window.addEventListener('hashchange', setCurrentSelection);
+  items.forEach(item => {
+    item.addEventListener("click", () => {
+      const configId = item.getAttribute("data-value");
+      const hash = configId.replace(/^config-/, "");
 
+      if (item.classList.contains("selected")) {
+        // Toggle off: clear hash
+        history.pushState("", document.title, window.location.pathname + window.location.search);
+        handleHashChange();
+      } else {
+        window.location.hash = hash;
+      }
+    });
+  });
 
-  if (window.location.hash) {
-    setCurrentSelection()
-  }
+  // Initial Load & Hash Change
+  const handleHashChange = () => {
+    const hash = window.location.hash.replace(/^#/, "");
+    if (hash) {
+      const configId = `config-${hash}`;
+      // Check if config exists
+      const exists = Array.from(items).some(item => item.getAttribute("data-value") === configId);
+      if (exists) {
+        showConfig(configId);
+      } else {
+        showConfigList();
+      }
+    } else {
+      showConfigList();
+    }
+  };
+
+  window.addEventListener("hashchange", handleHashChange);
 
-  showCurrentConfiguration();
+  // Run once on load
+  handleHashChange();
 });

data/app/configuration.html.erb

@@ -1,28 +1,28 @@
 <div class="ultra-settings-block">
-  <% if !configuration.class.yaml_config_disabled? && configuration.class.configuration_file.is_a?(Pathname) %>
-    <div class="ultra-settings-config-file">
-      <span class="ultra-settings-config-file-label">Configuration File:</span>
-      <code class="ultra-settings-config-file-path"><%= html_escape(relative_path(configuration.class.configuration_file)) %></code>
-      <% unless configuration.class.configuration_file&.exist? %>
-        <span class="ultra-settings-file-not-found">(File does not exist)</span>
-      <% end %>
-    </div>
-  <% end %>
+  <%= render_partial "config_description", configuration: configuration %>
 
   <div class="ultra-settings-fields">
     <% configuration.class.fields.each do |field| %>
       <% source = configuration.__source__(field.name) %>
+
       <div class="ultra-settings-field">
         <div class="ultra-settings-field-header">
           <div class="ultra-settings-field-name">
             <code><%= html_escape(field.name) %></code>
+
             <% if field.secret? %>
-              <span class="ultra-settings-field-badge ultra-settings-badge-secret">secret</span>
+              <span class="ultra-settings-field-badge ultra-settings-badge-secret">
+                secret
+              </span>
             <% end %>
+
             <% if field.static? %>
-              <span class="ultra-settings-field-badge ultra-settings-badge-static">static</span>
+              <span class="ultra-settings-field-badge ultra-settings-badge-static">
+                static
+              </span>
             <% end %>
           </div>
+
           <div class="ultra-settings-field-type">
             <%= html_escape(field.type) %>
           </div>
@@ -32,15 +32,20 @@
           <% if configuration[field.name].nil? %>
             <span class="ultra-settings-nil-value">nil</span>
           <% elsif field.secret? %>
-            <code class="ultra-settings-field-data-value"><%= html_escape(secret_value(configuration[field.name])) %></code>
+            <code class="ultra-settings-field-data-value">
+              <%= html_escape(secret_value(configuration[field.name])) %>
+            </code>
           <% else %>
-            <code class="ultra-settings-field-data-value"><%= html_escape(display_value(configuration[field.name])) %></code>
+            <code class="ultra-settings-field-data-value">
+              <%= html_escape(display_value(configuration[field.name])) %>
+            </code>
           <% end %>
         </div>
 
         <% unless field.description.to_s.empty? %>
           <div class="ultra-settings-field-description">
             <%= info_icon %>
+
             <div class="ultra-settings-description-text">
               <%= html_escape(field.description) %>
             </div>
@@ -48,61 +53,84 @@
         <% end %>
 
         <div class="ultra-settings-field-sources">
-          <% if field.env_var && !configuration.class.environment_variables_disabled? %>
+          <% sources = configuration.__available_sources__(field.name) %>
+          <% if sources.include?(:env) %>
             <div class="ultra-settings-source <%= 'ultra-settings-source-active' if source == :env %>">
               <span class="ultra-settings-source-type">
                 Environment Variable
               </span>
+
               <code class="ultra-settings-source-value">
                 <%= field.env_var %>
                 <%= show_defined_value(field.env_var, configuration.__value_from_source__(field.name, :env), field.secret?) %>
               </code>
+
               <% if source == :env %>
-                <span class="ultra-settings-source-indicator">Currently active</span>
+                <span class="ultra-settings-source-indicator">
+                  Currently active
+                </span>
               <% end %>
             </div>
           <% end %>
 
-          <% if field.runtime_setting && !configuration.class.runtime_settings_disabled? %>
+          <% if sources.include?(:settings) %>
             <div class="ultra-settings-source <%= 'ultra-settings-source-active' if source == :settings %>">
               <span class="ultra-settings-source-type">Runtime Setting</span>
+
               <code class="ultra-settings-source-value">
                 <%= field.runtime_setting %>
                 <%= show_defined_value(field.runtime_setting, configuration.__value_from_source__(field.name, :settings), field.secret?) %>
               </code>
+
               <% if source == :settings %>
-                <span class="ultra-settings-source-indicator">Currently active</span>
+                <span class="ultra-settings-source-indicator">
+                  Currently active
+                </span>
               <% end %>
+
               <% edit_url = UltraSettings.runtime_settings_url(name: field.runtime_setting, type: field.type, description: field.description) %>
+
               <% if edit_url %>
-                <a href="<%= html_escape(edit_url) %>" class="ultra-settings-edit-link" title="Edit <%= html_escape(field.runtime_setting) %>">
+                <a
+                  href="<%= html_escape(edit_url) %>"
+                  class="ultra-settings-edit-link"
+                  title="Edit <%= html_escape(field.runtime_setting) %>"
+                >
                   <%= edit_icon %>
                 </a>
               <% end %>
             </div>
           <% end %>
 
-          <% if field.yaml_key && !configuration.class.yaml_config_disabled? %>
+          <% if sources.include?(:yaml) %>
             <div class="ultra-settings-source <%= 'ultra-settings-source-active' if source == :yaml %>">
               <span class="ultra-settings-source-type">Configuration File</span>
+
               <code class="ultra-settings-source-value">
                 <%= field.yaml_key %>
                 <%= show_defined_value(field.yaml_key, configuration.__value_from_source__(field.name, :yaml), field.secret?) %>
               </code>
+
               <% if source == :yaml %>
-                <span class="ultra-settings-source-indicator">Currently active</span>
+                <span class="ultra-settings-source-indicator">
+                  Currently active
+                </span>
               <% end %>
             </div>
           <% end %>
 
-          <% if !field.default.nil? || source == :default %>
+          <% if sources.include?(:default) || source == :default %>
             <div class="ultra-settings-source <%= 'ultra-settings-source-active' if source == :default %>">
               <span class="ultra-settings-source-type">Default Value</span>
+
               <code class="ultra-settings-source-value">
                 <%= show_defined_value("Default Value", field.default, field.secret?) %>
               </code>
+
               <% if source == :default %>
-                <span class="ultra-settings-source-indicator">Currently active</span>
+                <span class="ultra-settings-source-indicator">
+                  Currently active
+                </span>
               <% end %>
             </div>
           <% end %>
@@ -114,10 +142,15 @@
   <dialog class="ultra-settings-dialog" closedby="any">
     <div class="ultra-settings-dialog-header">
       <div class="ultra-settings-dialog-title"></div>
-      <button class="ultra-settings-dialog-close" onclick="this.closest('.ultra-settings-dialog').close();">
+
+      <button
+        class="ultra-settings-dialog-close"
+        onclick="this.closest('.ultra-settings-dialog').close();"
+      >
         <%= close_icon %>
       </button>
     </div>
+
     <div class="ultra-settings-dialog-body">
       <code class="ultra-settings-field-data-value ultra-settings-dialog-value"></code>
     </div>

data/app/index.html.erb

@@ -2,25 +2,30 @@
 
 <div class="ultra-settings">
   <div class="ultra-settings-nav">
-    <form onsubmit="return false" style="margin-bottom: 0.5rem;">
-      <select class="<%= html_escape(select_class) %>" size="1" id="config-selector">
-        <% UltraSettings.__configuration_names__.sort.each do |name| %>
-          <% configuration = UltraSettings.send(name) %>
-          <% next if configuration.class.fields.empty? %>
+    <% configurations = UltraSettings.__configurations__.reject { |config| config.class.fields.empty? }.sort_by { |config| config.class.name.downcase } %>
 
-          <option value="config-<%= html_escape(name) %>"><%= html_escape(UltraSettings.send(name).class.name) %></option>
-        <% end %>
-      </select>
-    </form>
+    <% if configurations.size == 1 %>
+      <h2 class="ultra-settings-title">
+        <%= html_escape(configurations.first.class.name) %>
+      </h2>
+    <% else %>
+      <%= render_partial "select_menu", configurations: configurations %>
+    <% end %>
   </div>
 
-  <% UltraSettings.__configuration_names__.sort.each do |name| %>
-    <% configuration = UltraSettings.send(name) %>
-    <% next if configuration.class.fields.empty? %>
-
-    <div class="ultra-settings-configuration" id="config-<%= html_escape(name) %>" style="display:none;">
-      <%= UltraSettings::ConfigurationView.new(configuration).render(table_class: table_class) %>
-    </div>
+  <% if configurations.size == 1 %>
+    <%= UltraSettings::ConfigurationView.new(configurations.first).render(table_class: table_class) %>
+  <% else %>
+    <%= render_partial "config_list", configurations: configurations %>
+    <% configurations.each do |configuration| %>
+      <div
+        class="ultra-settings-configuration"
+        id="config-<%= html_escape(configuration.class.name) %>"
+        style="display:none;"
+      >
+        <%= UltraSettings::ConfigurationView.new(configuration).render(table_class: table_class) %>
+      </div>
+    <% end %>
   <% end %>
 </div>
 

data/lib/ultra_settings/application_view.rb

@@ -4,15 +4,15 @@ module UltraSettings
   # This class can render information about all configurations. It is used by the bundled
   # web UI, but you can use it to embed the configuration information in your own web pages.
   #
-  # The output will be a simple HTML drop down list that can be used to display an HTML element
-  # showing each configuration. You can specify the CSS class for the select element by passing
-  # the `select_class` option to the `render` method. By default the select element has
-  # the class `ultra-settings-select`.
+  # The output will be a simple HTML drop down menu that can be used to select the configuration
+  # you want to see.
   #
   # @example
   #  <h1>Application Configuration</h1>
-  #  <%= UltraSettings::ApplicationView.new.render(select_class: 'form-control') %>
+  #  <%= UltraSettings::ApplicationView.new.render %>
   class ApplicationView
+    include RenderHelper
+
     attr_reader :css
 
     # Initialize the application view with a color scheme.
@@ -25,10 +25,10 @@ module UltraSettings
 
     # Render the HTML for the configuration settings UI.
     #
-    # @param select_class [String] CSS class for the select element.
-    # @param table_class [String] CSS class for the table element (for backwards compatibility).
+    # @param select_class [String] Deprecated; no longer used.
+    # @param table_class [String] Deprecated; no longer used.
     # @return [String] The rendered HTML.
-    def render(select_class: "ultra-settings-select", table_class: "")
+    def render(select_class: nil, table_class: nil)
       html = ViewHelper.erb_template("index.html.erb").result(binding)
       html = html.html_safe if html.respond_to?(:html_safe)
       html
@@ -52,10 +52,6 @@ module UltraSettings
 
     private
 
-    def html_escape(value)
-      ERB::Util.html_escape(value)
-    end
-
     def javascript
       ViewHelper.read_app_file("application.js")
     end

data/lib/ultra_settings/configuration.rb

@@ -9,8 +9,20 @@ module UltraSettings
 
     @env_var_prefix = nil
     @runtime_setting_prefix = nil
+    @description = nil
 
     class << self
+      # Set a description for the configuration. This is optional. It will be displayed
+      # in the web UI if provided. On large projects with many configurations, this can
+      # help identify the purpose of each configuration.
+      #
+      # @param text [String] The description text.
+      # @return [void]
+      def description(text = nil)
+        @description = text.to_s.strip unless text.nil?
+        @description
+      end
+
       # Define a field on the configuration. This will create a getter method for the field.
       # The field value will be read from the environment, runtime settings, or a YAML file
       # and coerced to the specified type. Empty strings will be converted to nil.
@@ -27,14 +39,19 @@ module UltraSettings
       # @param static [Boolean] If true, the field value should never be changed. This is useful for
       #   fields that are used at startup to set static values in the application. Static field cannot
       #   be read from runtime settings.
-      # @param runtime_setting [String, Symbol] The name of the runtime setting to use for the field.
+      # @param secret [Boolean, Proc] If true, the field value will be obscured in the output of
+      #   to_hash. If a proc is provided, it will be called to determine if the field is secret.
+      # @param runtime_setting [String, Symbol, Boolean] The name of the runtime setting to use for the field.
       #   By default this will be the underscored name of the class plus a dot plus the field name
-      #   (i.e. MyServiceConfiguration#foo becomes "my_service.foo").
-      # @param env_var [String, Symbol] The name of the environment variable to use for the field.
+      #   (i.e. MyServiceConfiguration#foo becomes "my_service.foo"). If set to false, runtime settings
+      #   will be ignored for this field. This can be set to true to use the default name.
+      # @param env_var [String, Symbol, Boolean] The name of the environment variable to use for the field.
       #   By default this will be the underscored name of the class plus an underscore plus the field name
-      #   all in uppercase (i.e. MyServiceConfiguration#foo becomes "MY_SERVICE_FOO").
-      # @param yaml_key [String, Symbol] The name of the YAML key to use for the field. By default
-      #   this is the name of the field.
+      #   all in uppercase (i.e. MyServiceConfiguration#foo becomes "MY_SERVICE_FOO"). If set to false,
+      #   environment variables will be ignored for this field. This can be set to true to use the default name.
+      # @param yaml_key [String, Symbol, Boolean] The name of the YAML key to use for the field. By default
+      #   this is the name of the field. If set to false, YAML configuration will be ignored for this field.
+      #   This can be set to true to use the default name.
       # @return [void]
       def field(name, type: :string, description: nil, default: nil, default_if: nil, static: nil, secret: nil, runtime_setting: nil, env_var: nil, yaml_key: nil)
         name = name.to_s
@@ -145,7 +162,7 @@ module UltraSettings
       # directory (i.e. MyServiceConfiguration has a default config path of
       # "my_service.yml").
       #
-      # @param value [String, Pathname]
+      # @param value [String, Pathname, false, nil]
       # @return [void]
       def configuration_file=(value)
         value = nil if value == false
@@ -513,6 +530,22 @@ module UltraSettings
       end
     end
 
+    # Returns an array of the available data sources for the field.
+    #
+    # @param name [String, Symbol] the name of the field.
+    # @return [Array<Symbol>] The available sources (:env, :settings, :yaml, :default).
+    def __available_sources__(name)
+      field = self.class.send(:defined_fields)[name.to_s]
+      raise ArgumentError.new("Unknown field: #{name.inspect}") unless field
+
+      sources = []
+      sources << :env if field.env_var
+      sources << :settings if field.runtime_setting && UltraSettings.__runtime_settings__
+      sources << :yaml if field.yaml_key && self.class.configuration_file
+      sources << :default unless field.default.nil?
+      sources
+    end
+
     # Output the current state of the configuration as a hash. If the field is marked as a secret,
     # then the value will be a secure hash of the value instead of the value itself.
     #

data/lib/ultra_settings/configuration_view.rb

@@ -11,6 +11,8 @@ module UltraSettings
   #  <h1>Service Configuration</h1>
   #  <%= UltraSettings::ConfigurationView.new(ServiceConfiguration.instance).render %>
   class ConfigurationView
+    include RenderHelper
+
     # Initialize the configuration view with a configuration instance.
     #
     # @param configuration [UltraSettings::Configuration] The configuration instance to display.
@@ -38,10 +40,6 @@ module UltraSettings
 
     private
 
-    def html_escape(value)
-      ERB::Util.html_escape(value)
-    end
-
     def display_value(value)
       case value
       when Time
@@ -147,8 +145,6 @@ module UltraSettings
       HTML
     end
 
-    private
-
     def open_dialog_script
       <<~JAVASCRIPT.gsub(/\s+/, " ").tr('"', "'")
         this.closest('.ultra-settings-configuration').querySelector('.ultra-settings-dialog-title').textContent = this.dataset.label;

data/lib/ultra_settings/field.rb

@@ -16,12 +16,12 @@ module UltraSettings
     # @param type [Symbol] The type of the field.
     # @param description [String] The description of the field.
     # @param default [Object] The default value of the field.
-    # @param default_if [Proc] A proc that returns true if the default value should be used.
+    # @param default_if [Proc, Symbol] A proc that returns true if the default value should be used.
     # @param env_var [String, Symbol] The name of the environment variable to use for the field.
     # @param runtime_setting [String, Symbol] The name of the setting to use for the field.
     # @param yaml_key [String, Symbol] The name of the YAML key to use for the field.
     # @param static [Boolean] Whether or not the field is static and cannot be changed at runtime.
-    # @param secret [Boolean] Whether or not the field contains a value that should be kept secret.
+    # @param secret [Boolean, Proc] Whether or not the field contains a value that should be kept secret.
     def initialize(
       name:,
       type: :string,

data/lib/ultra_settings/render_helper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  # Helper methods for rendering views.
+  module RenderHelper
+    # HTML escape a value.
+    #
+    # @param value [String] The value to escape.
+    # @return [String] The escaped value.
+    def html_escape(value)
+      ERB::Util.html_escape(value)
+    end
+
+    # Render a partial template with the given locals.
+    #
+    # @param partial_name [String] The name of the partial template (without the leading underscore and file extension).
+    # @param locals [Hash] A hash of local variables to pass to the template.
+    # @return [String] The rendered HTML of the partial.
+    def render_partial(partial_name, locals = {})
+      template = ViewHelper.erb_template("_#{partial_name}.html.erb")
+      b = binding
+      locals.each do |key, value|
+        b.local_variable_set(key, value)
+      end
+      template.result(b)
+    end
+  end
+end

data/lib/ultra_settings/view_helper.rb

@@ -11,6 +11,7 @@ module UltraSettings
       # @param path [String] The path to the template file.
       # @return [ERB] The compiled ERB template.
       def erb_template(path)
+        @cache.clear if development_mode?
         @cache["erb:#{path}"] ||= ERB.new(read_app_file(path))
       end
 
@@ -19,6 +20,7 @@ module UltraSettings
       # @param path [String] The path to the file relative to the app directory.
       # @return [String] The contents of the file.
       def read_app_file(path)
+        @cache.clear if development_mode?
         @cache["file:#{path}"] ||= File.read(File.join(app_dir, path))
       end
 
@@ -28,6 +30,12 @@ module UltraSettings
       def app_dir
         File.expand_path(File.join("..", "..", "app"), __dir__)
       end
+
+      private
+
+      def development_mode?
+        ENV.fetch("RACK_ENV", "development") == "development"
+      end
     end
   end
 end

data/lib/ultra_settings.rb

@@ -14,6 +14,7 @@ require_relative "ultra_settings/config_helper"
 require_relative "ultra_settings/field"
 require_relative "ultra_settings/rack_app"
 require_relative "ultra_settings/view_helper"
+require_relative "ultra_settings/render_helper"
 require_relative "ultra_settings/web_view"
 require_relative "ultra_settings/application_view"
 require_relative "ultra_settings/configuration_view"
@@ -259,6 +260,19 @@ module UltraSettings
       @configurations.keys
     end
 
+    # Get an array of all of the configuration instances that have been loaded into memory.
+    #
+    # @return [Array<UltraSettings::Configuration>] The configuration instances.
+    # @api private
+    def __configurations__
+      @configurations.each do |name, class_name|
+        __load_config__(name, class_name)
+      end
+
+      config_classes = ObjectSpace.each_object(Class).select { |klass| klass < Configuration }
+      config_classes.collect(&:instance)
+    end
+
     private
 
     # Load a configuration class.

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ultra_settings
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.0
 platform: ruby
 authors:
 - Brian Durand
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,7 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - bbdurand@gmail.com
 executables: []
@@ -36,6 +34,9 @@ files:
 - MIT-LICENSE.txt
 - README.md
 - VERSION
+- app/_config_description.html.erb
+- app/_config_list.html.erb
+- app/_select_menu.html.erb
 - app/application.css
 - app/application.js
 - app/application_vars.css.erb
@@ -53,6 +54,7 @@ files:
 - lib/ultra_settings/field.rb
 - lib/ultra_settings/rack_app.rb
 - lib/ultra_settings/railtie.rb
+- lib/ultra_settings/render_helper.rb
 - lib/ultra_settings/uninitialized_runtime_settings.rb
 - lib/ultra_settings/version.rb
 - lib/ultra_settings/view_helper.rb
@@ -66,7 +68,6 @@ metadata:
   homepage_uri: https://github.com/bdurand/ultra_settings
   source_code_uri: https://github.com/bdurand/ultra_settings
   changelog_uri: https://github.com/bdurand/ultra_settings/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -81,8 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: UltraSettings is a Ruby gem that provides a flexible and documented approach
   to managing application configurations from multiple sources, including environment