ultra_settings 2.4.5 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0100a325a4565201a02667584d60b608a1fa0953c35a18c77ab014c205578853
-  data.tar.gz: 7728dd534db12acac88f7f9c23ee4cee76dddba40d7b89ba23f2873bcc873fe3
+  metadata.gz: 4682a4cd5e85642db5e79cfbb156109d6701b5ad09f6744a0b092bdfc3d9277c
+  data.tar.gz: 8c4a0d4350ce43b7ce4b1c0187bf80c27e2d33261d9bd349ce9155d8fb80a069
 SHA512:
-  metadata.gz: ae0580fb25bdad6baddec3ca0ba78bb506df187889ba976487280a850e931fbcb55d52684dfe06e46d38364432954ae87cb20e6c6fa7bcd530d7476bb9d7651e
-  data.tar.gz: 591b48efe616f8e288ecc1b5bdc1c116a2d4babcb0c32463eb5fe53ce1a7dffc739a762e46bdf54863e4f24dd5a245b47e515c64342e5c17916c76aab8638c93
+  metadata.gz: 00c9249324a0c6752dd1449d7b94101050e55aa1d27ba0c47cb3527bb0e8c5909233a64b98a0a0674528acae2413c5578c0097fabe9aaeda6a5b78c47a1854d7
+  data.tar.gz: a46516c99004973b58496e44c38c375b6698be941aba85fd2e3c0bf08db032c8b9c71ce371aef051bd8649419e5dc6752be0e1f259c2019ce3baa270c8b52460

data/ARCHITECTURE.md

@@ -0,0 +1,186 @@
+# UltraSettings Configuration Architecture
+
+This document describes the architecture of the UltraSettings Configuration and Field classes, which form the core of the configuration management system.
+
+## Overview
+
+The UltraSettings library provides a flexible configuration management system built around two primary classes:
+
+- **Configuration**: A singleton-based configuration manager that supports multiple data sources
+- **Field**: A field definition that encapsulates metadata and value resolution logic
+
+## Architecture Diagram
+
+```mermaid
+classDiagram
+    class Configuration {
+        <<Singleton>>
+        +ALLOWED_NAME_PATTERN : Regex
+        +ALLOWED_TYPES : Array~Symbol~
+        -@env_var_prefix : String
+        -@runtime_setting_prefix : String
+        -@ultra_settings_mutex : Mutex
+        -@ultra_settings_memoized_values : Hash
+        -@ultra_settings_override_values : Hash
+        -@ultra_settings_yaml_config : Hash
+
+        +field(name, **options) void
+        +fields() Array~Field~
+        +include_field?(name) Boolean
+        +env_var_prefix=(value) void
+        +env_var_prefix() String
+        +runtime_setting_prefix=(value) void
+        +runtime_setting_prefix() String
+        +configuration_file=(value) void
+        +configuration_file() Pathname
+        +override!(values, &block) Object
+        +load_yaml_config() Hash
+        +[](name) Object
+        +include?(name) Boolean
+        +__source__(name) Symbol
+        +__value_from_source__(name, source) Object
+        +__to_hash__() Hash
+        -__get_value__(name) Object
+        -__use_default?(value, default_if) Boolean
+        -__yaml_config__() Hash
+        -defined_fields() Hash~String, Field~
+        -root_name() String
+        -construct_env_var(name, env_var) String
+        -construct_runtime_setting(name, runtime_setting) String
+        -construct_yaml_key(name, yaml_key) String
+    }
+
+    class Field {
+        +name : String
+        +type : Symbol
+        +description : String
+        +default : Object
+        +default_if : Proc|Symbol
+        +env_var : String
+        +runtime_setting : String
+        +yaml_key : String
+        -@static : Boolean
+        -@secret : Boolean|Proc
+
+        +initialize(**options) void
+        +value(env, settings, yaml_config) Object
+        +source(env, settings, yaml_config) Symbol
+        +coerce(value) Object
+        +static?() Boolean
+        +secret?() Boolean
+        -fetch_value_and_source(**sources) Array
+        -runtime_setting_value(settings) Object
+        -yaml_value(yaml_config) Object
+    }
+
+    class Coerce {
+        <<Utility>>
+        +coerce_value(value, type) Object
+    }
+
+    Configuration "1" --> "*" Field : manages
+    Field --> Coerce : uses
+    Configuration --> Field : creates via field()
+
+    note for Configuration "Singleton pattern ensures single instance per class.\nSupports inheritance for configuration hierarchies.\nThread-safe with mutex protection."
+
+    note for Field "Immutable once created.\nSupports multiple data sources with precedence:\n1. Environment Variables\n2. Runtime Settings\n3. YAML Configuration\n4. Default Values"
+```
+
+## Key Components
+
+### Configuration Class
+
+The `Configuration` class serves as the primary interface for defining and accessing configuration values. Key characteristics:
+
+#### Singleton Pattern
+- Uses Ruby's `Singleton` module to ensure one instance per configuration class
+- Supports inheritance, allowing configuration subclasses to have their own singleton instances
+
+#### Field Definition
+- **`field(name, **options)`**: DSL method for defining configuration fields
+- Dynamically creates getter methods using `class_eval`
+- Supports various field types: `:string`, `:symbol`, `:integer`, `:float`, `:boolean`, `:datetime`, `:array`
+- Validates field names against `ALLOWED_NAME_PATTERN`
+
+#### Multi-Source Value Resolution
+Fields can pull values from multiple sources in order of precedence:
+1. **Environment Variables** - Highest priority
+2. **Runtime Settings** - Dynamic configuration
+3. **YAML Files** - File-based configuration
+4. **Default Values** - Fallback values
+
+#### Thread Safety
+- Uses `Mutex` for thread-safe operations
+- Protects memoized values and override values from race conditions
+
+#### Value Overrides
+- **`override!(values, &block)`**: Temporarily override field values within a block
+- Thread-local overrides allow different values per thread
+
+### Field Class
+
+The `Field` class encapsulates the metadata and behavior for individual configuration fields:
+
+#### Immutable Design
+- All attributes are frozen upon initialization
+- Ensures consistent behavior throughout the application lifecycle
+
+#### Value Resolution Logic
+- **`value(env:, settings:, yaml_config:)`**: Resolves field value from available sources
+- **`source(env:, settings:, yaml_config:)`**: Identifies which source provided the value
+- **`fetch_value_and_source()`**: Core resolution algorithm with source precedence
+
+#### Type Coercion
+- **`coerce(value)`**: Converts string values to appropriate types
+- Delegates to `Coerce` utility class for type-specific conversion logic
+
+#### Security Features
+- **`secret?`**: Marks fields containing sensitive data
+- Supports both boolean and callable (lambda) secret detection
+- Secret fields are masked in serialization methods
+
+#### Special Behaviors
+- **Static Fields**: Values cached and never change after first resolution
+- **Default Conditions**: Custom logic for when to use default values via `default_if`
+
+## Data Flow
+
+1. **Field Definition**: Developer calls `Configuration.field()` to define a configuration field
+2. **Field Creation**: A new `Field` instance is created and stored in the configuration class
+3. **Dynamic Method**: A getter method is dynamically created using `class_eval`
+4. **Value Access**: When the getter is called, it delegates to `__get_value__`
+5. **Source Resolution**: The field's `value()` method checks sources in precedence order
+6. **Type Coercion**: Raw string values are coerced to the appropriate type
+7. **Caching**: Static fields are memoized; others may use override values
+
+## Key Design Patterns
+
+### Factory Pattern
+The `field()` method acts as a factory for creating `Field` instances with appropriate defaults and validations.
+
+### Strategy Pattern
+Different data sources (environment, runtime settings, YAML) are handled through a consistent interface but with source-specific logic.
+
+### Template Method
+The value resolution follows a template where the algorithm is defined in `Field#fetch_value_and_source`, but source-specific retrieval is delegated to private methods.
+
+### Decorator Pattern
+Field overrides decorate the normal value resolution with temporary alternative values.
+
+## Inheritance Support
+
+Configuration classes support inheritance:
+- Subclasses inherit field definitions from parent classes
+- Each class maintains its own singleton instance
+- Prefixes and settings can be overridden per class
+- Field definitions are merged from parent to child
+
+## Thread Safety Considerations
+
+- **Mutex Protection**: Critical sections are protected with mutex locks
+- **Thread-Local Overrides**: Override values are stored per thread ID
+- **Immutable Fields**: Field definitions are immutable after creation
+- **Atomic Operations**: Value resolution is designed to be atomic
+
+This architecture provides a robust, flexible, and thread-safe configuration management system that can adapt to various deployment environments and configuration sources.

data/CHANGELOG.md

@@ -4,6 +4,26 @@ 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 support for passing the type in `UltraSettings.runtime_settings_url` as `${type}` in the URL.
+
+### Changed
+
+- Significantly updated the web UI to improve the layout and usability. The UI is no longer an HTML table and has a cleaner, more modern design.
+
+## 2.5.0
+
+### Added
+
+- Added mechanism for guarding against using runtime settings during initialization with the `UltraSettings::UninitializedRuntimeSettings` class.
+
+### Changed
+
+- Runtime settings will now try to load arrays from runtime settings using the `array` method if it is defined. This provides for better integration with the `super_settings` gem to avoid coercing values to and from strings.
+
 ## 2.4.5
 
 ### Fixed

data/README.md

@@ -170,6 +170,8 @@ end
 UltraSettings.runtime_settings = RedisRuntimeSettings.new
 ```
 
+The runtime settings implementation may also define an `array` method that takes a single parameter to return an array value. If this method is not implemented, then array values must be returned as single line CSV strings.
+
 #### Using the `super_settings` gem
 
 There is a companion gem [super_settings](https://github.com/bdurand/super_settings) that can be used as a drop in implementation for the runtime settings. You just need to set the runtime settings to the `SuperSettings` object.
@@ -178,6 +180,21 @@ There is a companion gem [super_settings](https://github.com/bdurand/super_setti
 UltraSettings.runtime_settings = SuperSettings
 ```
 
+#### Initialization Issues
+
+Runtime settings should not be used during application initialization. Often the values set during initialization are static so it can be misleading to use runtime settings for them. There can also be race conditions where the runtime settings implementation itself needs to be initialized. You can guard against unintended usage of runtime settings during initialization by using the `UltraSettings::UninitializedRuntimeSettings` class. This class will raise an error if you try to access a setting before the runtime settings have been initialized.
+
+```ruby
+# Set the runtime settings to the uninitialized class to raise errors if anything tries to use
+# reference a runtime setting during initializaton.
+UltraSettings.runtime_settings = UltraSettings::UninitializedRuntimeSettings
+
+# Switch to using the super_settings gem after the ActiveRecord has been initialized.
+ActiveSupport.on_load(:active_record) do
+  UltraSettings.runtime_settings = SuperSettings
+end
+```
+
 #### Customizing Runtime Settings
 
 By default settings will be loaded from runtime settings by constructing a prefix from the configuration class name (i.e. `Configs::MySettingsConfiguration` uses the prefix `configs.my_settings.`) with the field name appended to it (e.g. `configs.my_settings.host`). By default runtime settings will be in all lowercase letters.
@@ -194,7 +211,7 @@ You can customize the behavior of runtime setting names with the following optio
 
 - **Disabling Runtime Settings:** You can disable runtime settings as a default source for fields by setting `runtime_settings_disabled` to `true` in your configuration class. You can disable runtime settings on individual fields by setting `runtime_setting` on the field to `false`.
 
-- **Editing Links** You can specify a URL for editing runtime settings from the web UI by setting `UltraSettings.runtime_settings_url` to the desired URL. This will add links to the runtime settings in the web UI. You can use the placeholder `${name}` in the URL which will be replaced with the name of the runtime setting. If you are using the `super_settings` gem for runtime settings, then you can target a setting by adding `#edit=${name}` to the root URL where `super_settings` is mounted.
+- **Editing Links** You can specify a URL for editing runtime settings from the web UI by setting `UltraSettings.runtime_settings_url` to the desired URL. This will add links to the runtime settings in the web UI. You can use the placeholders `${name}` and `${type}` in the URL which will be replaced with the name and type of the runtime setting, respectively. If you are using the `super_settings` gem for runtime settings, then you can target a setting by adding `#edit=${name}&type=${type}` to the root URL where `super_settings` is mounted.
 
 If a setting value cannot be loaded from the runtime settings, then it's value will attempt to be loaded from a YAML file.
 
@@ -405,17 +422,25 @@ 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", table_class: "table table-striped") %>
+<%= UltraSettings::ApplicationView.new.render(select_class: "form-select") %>
 ```
 
-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 in an HTML table with navigation handled by an HTML select element. You can specify the CSS classes for these elements and use your own stylesheets to customize the appearance.
+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..
 
 You can also embed the view for individual configurations within your own views using the `UltraSettings::ConfigurationView` class if you want more customization:
 
 ```erb
 <h1>My Service Settings</h1>
 
-<%= UltraSettings::ConfigurationView.new(MyServiceConfiguration.instance).render(table_class: "table table-striped") %>
+<%= UltraSettings::ConfigurationView.new(MyServiceConfiguration.instance).render %>
+```
+
+You'll also need to include the CSS for the configuration view on your page.
+
+```erb
+<head>
+  <%= UltraSettings::ApplicationView.new.style_tag %>
+</head>
 ```
 
 ### Testing With UltraSettings

data/VERSION

@@ -1 +1 @@
-2.4.5
+2.6.0

data/app/application.css

@@ -6,41 +6,214 @@
   margin: 0;
 }
 
-.ultra-settings-table {
-  width: 100%;
-  max-width: 100%;
-  margin-bottom: 1rem;
-  border-collapse: collapse;
+/* Configuration file header */
+.ultra-settings-config-file {
+  margin-bottom: 1.5rem;
+  padding: 1rem;
+  background-color: var(--config-file-bg-color);
+  border: 1px solid var(--config-file-border-color);
+  border-radius: 0.375rem;
+}
+
+.ultra-settings-config-file-label {
+  font-weight: 600;
+  color: var(--text-color);
+  margin-right: 0.5rem;
+}
+
+.ultra-settings-config-file-path {
+  font-family: monospace;
+  font-size: 0.9rem;
+  color: var(--code-color);
+  font-weight: 600;
+}
+
+.ultra-settings-file-not-found {
+  color: var(--warning-color);
+  font-style: italic;
+  margin-left: 0.5rem;
+}
+
+/* Fields container */
+.ultra-settings-fields {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
 }
 
-.ultra-settings-table thead th {
-  vertical-align: bottom;
-  border-bottom: 2px solid var(--table-border-color);
-  background-color: var(--table-header-bg-color);
+/* Individual field card */
+.ultra-settings-field {
+  border: 1px solid var(--field-border-color);
+  border-radius: 0.5rem;
+  background-color: var(--field-bg-color);
+  overflow: hidden;
 }
 
-.ultra-settings-table td, .ultra-settings-table th {
-  padding: 0.75rem;
-  vertical-align: top;
-  border-top: 1px solid var(--table-border-color);
+/* Field header */
+.ultra-settings-field-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 0.75rem 1rem;
+  background-color: var(--field-header-bg-color);
+  border-bottom: 1px solid var(--field-border-color);
 }
 
-.ultra-settings-table tbody tr:nth-of-type(odd) {
-  background-color: var(--alt-row-color);
+.ultra-settings-field-name {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
 }
 
-.ultra-settings-table code {
+.ultra-settings-field-name code {
   font-family: monospace;
-  font-size: 0.9rem;
-  display: inline;
+  font-size: 1rem;
+  font-weight: 600;
   color: var(--code-color);
+}
+
+.ultra-settings-field-type {
+  font-size: 0.875rem;
   font-weight: 600;
+  color: var(--type-color);
+  text-transform: uppercase;
+  letter-spacing: 0.025em;
+}
+
+/* Field badges */
+.ultra-settings-field-badge {
+  display: inline-block;
+  padding: 0.125rem 0.5rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.025em;
+  border-radius: 0.25rem;
+}
+
+.ultra-settings-badge-secret {
+  background-color: var(--secret-badge-bg-color);
+  color: var(--secret-badge-text-color);
+}
+
+.ultra-settings-badge-static {
+  background-color: var(--static-badge-bg-color);
+  color: var(--static-badge-text-color);
+}
+
+/* Field value */
+.ultra-settings-field-value {
+  padding: 1rem;
+  background-color: var(--value-bg-color);
+  border-bottom: 1px solid var(--field-border-color);
+}
+
+.ultra-settings-field-value code {
+  font-family: monospace;
+  font-size: 0.95rem;
+  word-break: break-all;
+  color: var(--value-text-color);
+  background-color: var(--value-code-bg-color);
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.25rem;
+  border: 1px solid var(--value-code-border-color);
 }
 
-.ultra-settings-table em {
-  color: var(--em-color);
+.ultra-settings-nil-value {
   font-style: italic;
+  color: var(--nil-color);
+  font-size: 0.9rem;
+}
+
+/* Field description */
+.ultra-settings-field-description {
+  padding: 0.75rem 1rem;
+  color: var(--description-color);
   font-size: 0.9rem;
+  line-height: 1.5;
+  border-bottom: 1px solid var(--field-border-color);
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
+}
+
+.ultra-settings-description-text {
+  flex: 1;
+}
+
+.ultra-settings-info-icon {
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+  margin-top: 0.125rem; /* Align with first line of text based on line-height */
+  color: var(--description-color);
+}
+
+/* Sources section */
+.ultra-settings-field-sources {
+  padding: 0.5rem;
+}
+
+.ultra-settings-source {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.5rem 0.75rem;
+  margin-bottom: 0.25rem;
+  border-radius: 0.25rem;
+  background-color: var(--source-bg-color);
+  border: 1px solid var(--source-border-color);
+  transition: all 0.2s ease;
+}
+
+.ultra-settings-source-active {
+  background-color: var(--source-active-bg-color);
+  border-color: var(--source-active-border-color);
+}
+
+.ultra-settings-source-type {
+  font-size: 0.8rem;
+  font-weight: 500;
+  color: var(--source-type-color);
+  text-transform: uppercase;
+  letter-spacing: 0.025em;
+  min-width: 120px;
+}
+
+.ultra-settings-source-value {
+  font-family: monospace;
+  font-size: 0.85rem;
+  color: var(--source-value-color);
+  flex: 1;
+  margin: 0 0.75rem;
+  word-break: break-all;
+}
+
+.ultra-settings-source-indicator {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--source-indicator-color);
+  text-transform: uppercase;
+  letter-spacing: 0.025em;
+}
+
+.ultra-settings-edit-link {
+  color: var(--edit-link-color);
+  text-decoration: none;
+  margin-left: 0.5rem;
+  opacity: 0.7;
+  transition: opacity 0.2s ease;
+  display: inline-flex;
+  align-items: center;
+}
+
+.ultra-settings-edit-link:hover {
+  opacity: 1;
+}
+
+.ultra-settings-edit-icon {
+  width: 16px;
+  height: 16px;
 }
 
 .ultra-settings-select {

data/app/application_vars.css.erb

@@ -1,13 +1,42 @@
 <% unless color_scheme == :dark %>
-  .ultra-settings {
-    --table-header-bg-color: #fff;
-    --table-border-color: #dee2e6;
-    --alt-row-color: rgba(0, 0, 0, .05);
-    --form-control-color: #495057;
+  .ultra-settings, .ultra-settings-block {
+    --form-control-color: #484848;
     --form-control-bg-color: #fff;
-    --form-control-border-color: #ced4da;
-    --code-color: darkred;
-    --em-color: gray;
+    --form-control-border-color: #e8e8e8;
+    --code-color: #d63384;
+
+    /* Card layout colors */
+    --config-file-bg-color: #f8f8f8;
+    --config-file-border-color: #e8e8e8;
+    --field-bg-color: #ffffff;
+    --field-border-color: #b8b8b8;
+    --field-header-bg-color: #f8f8f8;
+    --value-bg-color: #fdfdfe;
+    --value-text-color: #212529;
+    --value-code-bg-color: #f8f8f8;
+    --value-code-border-color: #e8e8e8;
+    --type-color: #6c757d;
+    --description-color: #4a83b5;
+    --nil-color: #6c757d;
+    --warning-color: #dc3545;
+
+    /* Source colors */
+    --source-bg-color: #f8f9fa;
+    --source-border-color: #e9ecef;
+    --source-active-bg-color: #e7f3ff;
+    --source-active-border-color: #0d6efd;
+    --source-type-color: #666666;
+    --source-value-color: #666666;
+    --source-indicator-color: #0d6efd;
+
+    /* Badge colors */
+    --secret-badge-bg-color: #dc3545;
+    --secret-badge-text-color: #ffffff;
+    --static-badge-bg-color: #888888;
+    --static-badge-text-color: #ffffff;
+
+    /* Edit link */
+    --edit-link-color: #0d6efd;
   }
 <% end %>
 
@@ -15,15 +44,45 @@
   @media (prefers-color-scheme: dark) {
 <% end %>
 <% if color_scheme == :system || color_scheme == :dark %>
-  .ultra-settings {
-    --table-header-bg-color: #333;
-    --table-border-color: #555;
-    --alt-row-color: rgba(0, 0, 0, .30);
+  .ultra-settings, .ultra-settings-block {
     --form-control-color: #eee;
     --form-control-bg-color: #666;
     --form-control-border-color: #555;
-    --code-color: pink;
-    --em-color: #999;
+    --code-color: #ff6b9d;
+    --em-color: #adb5bd;
+
+    /* Card layout colors */
+    --config-file-bg-color: #2b2b2b;
+    --config-file-border-color: #444;
+    --field-bg-color: #1e1e1e;
+    --field-border-color: #444;
+    --field-header-bg-color: #2b2b2b;
+    --value-bg-color: #252525;
+    --value-text-color: #e9ecef;
+    --value-code-bg-color: #2b2b2b;
+    --value-code-border-color: #444;
+    --type-color: #adb5bd;
+    --description-color: #a9d9f8;
+    --nil-color: #cdcecfff;
+    --warning-color: #dc3545;
+
+    /* Source colors */
+    --source-bg-color: #2b2b2b;
+    --source-border-color: #444444;
+    --source-active-bg-color: #1a3a52;
+    --source-active-border-color: #0d6efd;
+    --source-type-color: #adb5bd;
+    --source-value-color: #ced4da;
+    --source-indicator-color: #6ea8fe;
+
+    /* Badge colors */
+    --secret-badge-bg-color: #dc3545;
+    --secret-badge-text-color: #ffffff;
+    --static-badge-bg-color: #6c757d;
+    --static-badge-text-color: #ffffff;
+
+    /* Edit link */
+    --edit-link-color: #a7c6f5;
   }
 <% end %>
 <% if color_scheme == :system %>

data/app/configuration.html.erb

@@ -1,141 +1,112 @@
-  <table class="<%= html_escape(table_class.to_s) %>">
-    <thead>
-      <% if !configuration.class.yaml_config_disabled? && configuration.class.configuration_file.is_a?(Pathname) %>
-        <tr>
-          <th colspan="6">
-            Configuration File:
-            <span style="font-weight: normal;">
-              <%= html_escape(relative_path(configuration.class.configuration_file)) %>
-              <% unless configuration.class.configuration_file&.exist? %>
-                <em>(File does not exist)</em>
-              <% end %>
-            </span>
-          </th>
-        </tr>
+<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 %>
-      <tr>
-        <th>Name</th>
-        <th>Value</th>
-        <th>Type</th>
-        <th>Notes</th>
-      </tr>
-    </thead>
-    <tbody translate="no">
-      <% configuration.class.fields.each do |field| %>
-        <% source = configuration.__source__(field.name) %>
-        <tr>
-          <td>
-            <code><%= html_escape(field.name) %></code>
-          </td>
+    </div>
+  <% end %>
 
-          <td style="word-wrap: break-word; max-width:30em;">
-            <% if configuration[field.name].nil? %>
-              <em>nil</em>
-            <% elsif field.secret? %>
-              <%= html_escape(secret_value(configuration[field.name])) %>
-            <% else %>
-              <%= html_escape(display_value(configuration[field.name])) %>
+  <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>
             <% end %>
-          </td>
-
-          <td>
-            <%= html_escape(field.type) %>
-            <%
-              options = []
-              options << 'static' if field.static?
-              options << 'secret' if field.secret?
-            %>
-            <% unless options.empty? %>
-              <div>
-                <em><%= html_escape(options.join(', ')) %></em>
-              </div>
+            <% if field.static? %>
+              <span class="ultra-settings-field-badge ultra-settings-badge-static">static</span>
             <% end %>
-          </td>
+          </div>
+          <div class="ultra-settings-field-type">
+            <%= html_escape(field.type) %>
+          </div>
+        </div>
 
-          <td style="word-wrap: break-word;">
-            <% unless field.description.to_s.empty? %>
-              <div>
-                <%= html_escape(field.description) %>
-              </div>
-            <% end %>
+        <div class="ultra-settings-field-value">
+          <% if configuration[field.name].nil? %>
+            <span class="ultra-settings-nil-value">nil</span>
+          <% elsif field.secret? %>
+            <code><%= html_escape(secret_value(configuration[field.name])) %></code>
+          <% else %>
+            <code><%= html_escape(display_value(configuration[field.name])) %></code>
+          <% end %>
+        </div>
+
+        <% unless field.description.to_s.empty? %>
+          <div class="ultra-settings-field-description">
+            <svg class="ultra-settings-info-icon" width="16" height="16" fill="currentColor">
+              <use href="#info-icon"/>
+            </svg>
+            <div class="ultra-settings-description-text">
+              <%= html_escape(field.description) %>
+            </div>
+          </div>
+        <% end %>
 
-            <ul style="margin: 0 0 0 1rem; padding: 0; list-style-type: disc; list-style-position: outside;">
-              <% if field.env_var && !configuration.class.environment_variables_disabled? %>
-                <li>
-                  <% if source == :env %>
-                    <strong>
-                    Currently
-                  <% else %>
-                    Can be
-                  <% end %>
-                  set with the environment variable
-                  <code><%= show_defined_value(field.env_var, configuration.__value_from_source__(field.name, :env), field.secret?) %></code>
-                  <% if source == :env %>
-                    </strong>
-                  <% end %>
-                </li>
+        <div class="ultra-settings-field-sources">
+          <% if field.env_var && !configuration.class.environment_variables_disabled? %>
+            <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"><%= 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>
               <% end %>
-              <% if field.runtime_setting && !configuration.class.runtime_settings_disabled? %>
-                <li>
-                  <% if source == :settings %>
-                    <strong>
-                    Currently
-                  <% else %>
-                    Can be
-                  <% end %>
-                  set with the runtime setting
-                  <code><%= show_defined_value(field.runtime_setting, configuration.__value_from_source__(field.name, :settings), field.secret?) %></code>
-                  <% if source == :settings %>
-                    </strong>
-                  <% end %>
+            </div>
+          <% end %>
 
-                  <% edit_url = UltraSettings.runtime_settings_url(field.runtime_setting) %>
-                  <% if edit_url %>
-                    <a href="<%= html_escape(edit_url) %>" title="Edit <%= html_escape(field.runtime_setting) %>" style="text-decoration: none; color: inherit; vertical-align: middle;">
-                      <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-pencil-square" viewBox="0 0 16 16">
-                        <path d="M15.502 1.94a.5.5 0 0 1 0 .706L14.459 3.69l-2-2L13.502.646a.5.5 0 0 1 .707 0l1.293 1.293zm-1.75 2.456-2-2L4.939 9.21a.5.5 0 0 0-.121.196l-.805 2.414a.25.25 0 0 0 .316.316l2.414-.805a.5.5 0 0 0 .196-.12l6.813-6.814z"/>
-                        <path fill-rule="evenodd" d="M1 13.5A1.5 1.5 0 0 0 2.5 15h11a1.5 1.5 0 0 0 1.5-1.5v-6a.5.5 0 0 0-1 0v6a.5.5 0 0 1-.5.5h-11a.5.5 0 0 1-.5-.5v-11a.5.5 0 0 1 .5-.5H9a.5.5 0 0 0 0-1H2.5A1.5 1.5 0 0 0 1 2.5z"/>
-                      </svg>
-                    </a>
-                  <% end %>
-                </li>
+          <% if field.runtime_setting && !configuration.class.runtime_settings_disabled? %>
+            <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"><%= 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>
               <% end %>
-              <% if field.yaml_key && !configuration.class.yaml_config_disabled? %>
-                <li>
-                  <% if source == :yaml %>
-                    <strong>
-                    Currently
-                  <% else %>
-                    Can be
-                  <% end %>
-                  set with the configuration file key
-                  <code><%= show_defined_value(field.yaml_key, configuration.__value_from_source__(field.name, :yaml), field.secret?) %></code>
-                  <% if source == :yaml %>
-                    </strong>
-                  <% end %>
-                </li>
+              <% edit_url = UltraSettings.runtime_settings_url(field.runtime_setting, field.type) %>
+              <% if edit_url %>
+                <a href="<%= html_escape(edit_url) %>" class="ultra-settings-edit-link" title="Edit <%= html_escape(field.runtime_setting) %>">
+                  <svg class="ultra-settings-edit-icon" width="16" height="16" fill="currentColor">
+                    <use href="#edit-icon"/>
+                  </svg>
+                </a>
               <% end %>
-              <% if field.default.nil? %>
-                <% if source == :default %>
-                  <li>
-                    <strong>Not set</strong>
-                  </li>
-                <% end %>
-              <% else %>
-                <li>
-                  <% if source == :default %>
-                    <strong>
-                      Currently set with the
-                      <%= show_defined_value("default value", field.default, field.secret?) %>.
-                    </strong>
-                  <% else %>
-                    This field has a <%= show_defined_value("default value", field.default, field.secret?) %>.
-                  <% end %>
-                </li>
+            </div>
+          <% end %>
+
+          <% if field.yaml_key && !configuration.class.yaml_config_disabled? %>
+            <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"><%= 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>
               <% end %>
-            </ul>
-          </td>
-        </tr>
-      <% end %>
-    </tbody>
-  </table>
+            </div>
+          <% end %>
+
+          <% if field.default.nil? %>
+            <% if source == :default %>
+              <div class="ultra-settings-source ultra-settings-source-active">
+                <span class="ultra-settings-source-type">Default Value</span>
+                <span class="ultra-settings-source-value"><em>Not set</em></span>
+                <span class="ultra-settings-source-indicator">Currently active</span>
+              </div>
+            <% end %>
+          <% else %>
+            <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("", field.default, field.secret?) %></code>
+              <% if source == :default %>
+                <span class="ultra-settings-source-indicator">Currently active</span>
+              <% end %>
+            </div>
+          <% end %>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/index.html.erb

@@ -1,3 +1,19 @@
+<%= style_tag %>
+
+<!-- SVG Icons -->
+<svg style="display: none;" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <symbol id="edit-icon" viewBox="0 0 16 16">
+      <path d="M15.502 1.94a.5.5 0 0 1 0 .706L14.459 3.69l-2-2L13.502.646a.5.5 0 0 1 .707 0l1.293 1.293zm-1.75 2.456-2-2L4.939 9.21a.5.5 0 0 0-.121.196l-.805 2.414a.25.25 0 0 0 .316.316l2.414-.805a.5.5 0 0 0 .196-.12l6.813-6.814z"/>
+      <path fill-rule="evenodd" d="M1 13.5A1.5 1.5 0 0 0 2.5 15h11a1.5 1.5 0 0 0 1.5-1.5v-6a.5.5 0 0 0-1 0v6a.5.5 0 0 1-.5.5h-11a.5.5 0 0 1-.5-.5v-11a.5.5 0 0 1 .5-.5H9a.5.5 0 0 0 0-1H2.5A1.5 1.5 0 0 0 1 2.5z"/>
+    </symbol>
+    <symbol id="info-icon" viewBox="0 0 16 16">
+      <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14m0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16"/>
+      <path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0"/>
+    </symbol>
+  </defs>
+</svg>
+
 <div class="ultra-settings">
   <div class="ultra-settings-nav">
     <form onsubmit="return false" style="margin-bottom: 0.5rem;">

data/app/layout.html.erb

@@ -7,8 +7,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <meta name="format-detection" content="telephone=no email=no date=no address=no">
     <style type="text/css">
-      <%= @layout_css %>
-      <%= css %>
+      <%= layout_css %>
     </style>
   </head>
   <body>

data/lib/ultra_settings/application_view.rb

@@ -4,44 +4,34 @@ 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 table
-  # showing each configuration. You can specify the CSS class for the select element and the tables
-  # by passing the `select_class` and `table_class` option to the `render` method. By default the
-  # select elewment have the class `ultra-settings-select` and the table will have the class
-  # `ultra-settings-table`.
+  # 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`.
   #
   # @example
   #  <h1>Application Configuration</h1>
-  #  <%= UltraSettings::ApplicationView.new.render(select_class: 'form-control', table_class: "table table-striped") %>
+  #  <%= UltraSettings::ApplicationView.new.render(select_class: 'form-control') %>
   class ApplicationView
-    @template = nil
+    attr_reader :css
 
-    class << self
-      def template
-        @template ||= ERB.new(read_app_file("index.html.erb"))
-      end
-
-      def javascript
-        @javascript = read_app_file("application.js")
-      end
-
-      private
-
-      def read_app_file(path)
-        File.read(File.join(app_dir, path))
-      end
-
-      def app_dir
-        File.expand_path(File.join("..", "..", "app"), __dir__)
-      end
+    def initialize(color_scheme: :light)
+      @css = application_css(color_scheme)
+      @css = @css.html_safe if @css.respond_to?(:html_safe)
     end
 
-    def render(select_class: "ultra-settings-select", table_class: "ultra-settings-table")
-      html = self.class.template.result(binding)
+    def render(select_class: "ultra-settings-select", table_class: "")
+      html = ViewHelper.erb_template("index.html.erb").result(binding)
       html = html.html_safe if html.respond_to?(:html_safe)
       html
     end
 
+    def style_tag
+      tag = "<style type=\"text/css\">\n#{css}\n</style>"
+      tag = tag.html_safe if tag.respond_to?(:html_safe)
+      tag
+    end
+
     def to_s
       render
     end
@@ -53,7 +43,13 @@ module UltraSettings
     end
 
     def javascript
-      self.class.javascript
+      ViewHelper.read_app_file("application.js")
+    end
+
+    def application_css(color_scheme)
+      vars = ViewHelper.erb_template("application_vars.css.erb").result(binding).strip
+      css = ViewHelper.read_app_file("application.css").strip
+      "#{vars}\n#{css}"
     end
   end
 end

data/lib/ultra_settings/configuration_view.rb

@@ -1,42 +1,23 @@
 # frozen_string_literal: true
 
 module UltraSettings
-  # This class can render information about a configuration in an HTML table. It is used by the
+  # This class can render information about a configuration in a clean card-based layout. 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 an HTML table. You can specify the CSS class for the table by passing the
-  # `table_class` option to the `render` method. By default the table will have the class
-  # `ultra-settings-table`.
+  # The output will be HTML with a card-based layout for better readability. The `table_class` option is
+  # still supported for backward compatibility but is no longer used in the new card layout.
   #
   # @example
   #  <h1>Service Configuration</h1>
-  #  <%= UltraSettings::ConfigurationView.new(ServiceConfiguration.instance).render(table_class: "table table-striped") %>
+  #  <%= UltraSettings::ConfigurationView.new(ServiceConfiguration.instance).render %>
   class ConfigurationView
-    @template = nil
-
-    class << self
-      def template
-        @template ||= ERB.new(read_app_file("configuration.html.erb"))
-      end
-
-      private
-
-      def read_app_file(path)
-        File.read(File.join(app_dir, path))
-      end
-
-      def app_dir
-        File.expand_path(File.join("..", "..", "app"), __dir__)
-      end
-    end
-
     def initialize(configuration)
       @configuration = configuration
     end
 
-    def render(table_class: "ultra-settings-table")
+    def render(table_class: "")
       configuration = @configuration
-      html = self.class.template.result(binding)
+      html = ViewHelper.erb_template("configuration.html.erb").result(binding)
       html = html.html_safe if html.respond_to?(:html_safe)
       html
     end

data/lib/ultra_settings/field.rb

@@ -99,7 +99,7 @@ module UltraSettings
       value = env[env_var] if env && env_var
       value = nil if value == ""
       if value.nil?
-        value = settings[runtime_setting] if settings && runtime_setting
+        value = runtime_setting_value(settings)
         value = nil if value == ""
         if value.nil?
           value = yaml_value(yaml_config)
@@ -117,6 +117,18 @@ module UltraSettings
       [value, source]
     end
 
+    def runtime_setting_value(settings)
+      return nil unless settings && runtime_setting
+
+      if type == :array && settings.respond_to?(:array)
+        if settings.method(:array).parameters.count { |ptype, pname| ptype == :req } == 1
+          return settings.array(runtime_setting)
+        end
+      end
+
+      settings[runtime_setting]
+    end
+
     def yaml_value(yaml_config)
       return nil unless yaml_config && yaml_key
 

data/lib/ultra_settings/railtie.rb

@@ -9,7 +9,6 @@ module UltraSettings
     config.ultra_settings = ActiveSupport::OrderedOptions.new
     config.ultra_settings.auto_load_directories ||= [File.join("app", "configurations")]
 
-    # initializer "ultra_settings.before_bootstrap", before: :bootstrap_hook do
     config.before_configuration do
       UltraSettings::Configuration.yaml_config_env ||= Rails.env
       UltraSettings::Configuration.yaml_config_path ||= Rails.root.join("config")

data/lib/ultra_settings/uninitialized_runtime_settings.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  # This class is used to represent runtime settings that have not been initialized yet.
+  # You can use this to protect your application from accidentally accessing runtime settings
+  # before they are initialized. Doing this can cquse unexpected behavior if the runtime settings
+  # engine has not yet been initialized. For instance, if your runtime settings enging reads from
+  # a database it would not be available until the database connection is established.
+  #
+  # The intention of this class is to set it a the runtime settings at the beginning of initialization
+  # and then set the actual runtime settings engine after the initialization is complete. It will
+  # act as a guard to prevent invalid runtime settings backed configurations from being used during
+  # initialization.
+  #
+  # @example
+  #
+  # UltraSettings.runtime_settings = UltraSettings::UninitializedRuntimeSettings
+  # ActiveSupport.on_load(:active_record) do
+  #   UltraSettings.runtime_settings = SuperSettings
+  # end
+  class UninitializedRuntimeSettings
+    class Error < StandardError
+    end
+
+    class << self
+      def [](key)
+        raise Error.new("Attempt to call runtime setting #{key} during initialization")
+      end
+    end
+  end
+end

data/lib/ultra_settings/view_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  # Base class for rendering views.
+  module ViewHelper
+    @cache = {}
+
+    class << self
+      def erb_template(path)
+        @cache["erb:#{path}"] ||= ERB.new(read_app_file(path))
+      end
+
+      def read_app_file(path)
+        @cache["file:#{path}"] ||= File.read(File.join(app_dir, path))
+      end
+
+      def app_dir
+        File.expand_path(File.join("..", "..", "app"), __dir__)
+      end
+    end
+  end
+end

data/lib/ultra_settings/web_view.rb

@@ -3,15 +3,14 @@
 module UltraSettings
   # Helper class for rendering the settings information in an HTML page.
   class WebView
-    attr_reader :css
+    attr_reader :layout_css
 
     # @param color_scheme [Symbol] The color scheme to use in the UI. This can be `:light`,
     #  `:dark`, or `:system`. The default is `:light`.
     def initialize(color_scheme: :light)
-      color_scheme = (color_scheme || :light).to_sym
-      @layout_template = erb_template("layout.html.erb")
-      @layout_css = layout_css(color_scheme)
-      @css = application_css(color_scheme)
+      @color_scheme = (color_scheme || :light).to_sym
+      @layout_template = ViewHelper.erb_template("layout.html.erb")
+      @layout_css = scheme_layout_css(@color_scheme)
     end
 
     def render_settings
@@ -19,32 +18,14 @@ module UltraSettings
     end
 
     def content
-      UltraSettings::ApplicationView.new.render
+      UltraSettings::ApplicationView.new(color_scheme: @color_scheme).render
     end
 
     private
 
-    def erb_template(path)
-      ERB.new(read_app_file(path))
-    end
-
-    def read_app_file(path)
-      File.read(File.join(app_dir, path))
-    end
-
-    def app_dir
-      File.expand_path(File.join("..", "..", "app"), __dir__)
-    end
-
-    def layout_css(color_scheme)
-      vars = erb_template("layout_vars.css.erb").result(binding)
-      css = read_app_file("layout.css")
-      "#{vars}\n#{css}"
-    end
-
-    def application_css(color_scheme)
-      vars = erb_template("application_vars.css.erb").result(binding)
-      css = read_app_file("application.css")
+    def scheme_layout_css(color_scheme)
+      vars = ViewHelper.erb_template("layout_vars.css.erb").result(binding)
+      css = ViewHelper.read_app_file("layout.css")
       "#{vars}\n#{css}"
     end
   end

data/lib/ultra_settings.rb

@@ -13,9 +13,11 @@ require_relative "ultra_settings/coerce"
 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/web_view"
 require_relative "ultra_settings/application_view"
 require_relative "ultra_settings/configuration_view"
+require_relative "ultra_settings/uninitialized_runtime_settings"
 require_relative "ultra_settings/yaml_config"
 require_relative "ultra_settings/version"
 
@@ -181,11 +183,12 @@ module UltraSettings
     # @param name [String] The name of the setting.
     # @return [String, nil]
     # @api private
-    def runtime_settings_url(name)
+    def runtime_settings_url(name, type)
       url = @runtime_settings_url.to_s
       return nil if url.empty?
 
-      url.gsub("${name}", URI.encode_www_form_component(name))
+      url = url.gsub("${name}", URI.encode_www_form_component(name.to_s))
+      url.gsub("${type}", URI.encode_www_form_component(type.to_s))
     end
 
     def fields_secret_by_default=(value)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ultra_settings
 version: !ruby/object:Gem::Version
-  version: 2.4.5
+  version: 2.6.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-11 00:00:00.000000000 Z
+date: 2025-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -31,6 +31,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ARCHITECTURE.md
 - CHANGELOG.md
 - MIT-LICENSE.txt
 - README.md
@@ -52,7 +53,9 @@ files:
 - lib/ultra_settings/field.rb
 - lib/ultra_settings/rack_app.rb
 - lib/ultra_settings/railtie.rb
+- lib/ultra_settings/uninitialized_runtime_settings.rb
 - lib/ultra_settings/version.rb
+- lib/ultra_settings/view_helper.rb
 - lib/ultra_settings/web_view.rb
 - lib/ultra_settings/yaml_config.rb
 - ultra_settings.gemspec