super_settings 2.4.0 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a409f83b0e25f1a6822167604061a205a9f2ba9144776ae12c917a28934af8aa
-  data.tar.gz: 7b58a037a30031cbdadaf2afbfcaf37faa0c6d48dee38a6d0a61b7559d99806a
+  metadata.gz: e851110a7e8ebb10348b536a94121aab3c6657ef7c8115f3de6fd7adcd5f1a3b
+  data.tar.gz: 3aa309b399ee775cf5427d5e14a0b3f143e3ba0b441da4bcf41708f7806e2c17
 SHA512:
-  metadata.gz: 797087d1072b5f2dd88fee2f361ad2e4dc53d44145ee57f2a17f0e31fc0fb88c99ddcc73cac8d5f3e39ad5a00d56123748c544fb724e1ac8ef2945d8a004ad19
-  data.tar.gz: d586e20dac006fde52f5da754acf7c154a891bf82e4682c7b90b5a432c7261f0a60caaa951783c4586dc960a1d31f3865680b8732142cd0ccb8e26acac80a5ee
+  metadata.gz: 79ba25dcd135459a8a5332aac5c4807fb04a183e573ae761ecd76b4b079d1772895fc2917ac2fe2c26e723193020eb43dbbb50d672dfb4f9d5e89ecd4d3a3c29
+  data.tar.gz: 6190dca1e68e103c982696ab7075a20e39a32e4ab5cf68d213cb679e552c475feb61d4ed111d151392a1f37010c42e3b69810ebeb7d6de5ee9a46239ca1ffbdf

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.4.1
+
+### Added
+
+- Incoming links to the web UI now support specifying a description for the setting being edited by passing `description=description_text` in the URL hash. For example, `#edit=port&type=integer&description=Port%20number%20for%20the%20server` will open the setting with the key `port` for editing as an integer and pre-fill the description field.
+
 ## 2.4.0
 
 ### Added

data/README.md

@@ -181,10 +181,12 @@ Then go to http://localhost:3000/settings in your browser.
 
 It is not required to use the bundled Web UI. You can implement your own UI using the `SuperSettings::Setting` model.
 
-You can link directly to editing a setting by passing `#edit=key` in the URL hash. This will open the Web UI with the setting with the key `key` selected for editing. You can also `type` in the URL hash to specify the value type for the setting. For example, `#edit=port&type=integer` will open the setting with the key `port` for editing as an integer.
+You can link directly to editing a setting by passing `#edit=key` in the URL hash. This will open the Web UI with the setting with the key `key` selected for editing.
+
+You can also add `type` and `description` as parameters in the URL hash to specify the values to pre-fill for the setting if it doesn't already exist. For example, `#edit=port&type=integer&description=Server+port+number` will open the setting with the key `port` for editing as an integer with the description filled in if it doesn't already exist. If the setting does exist, then the type and description will be ignored.
 
 ```html
-<a href="/settings#edit=port&type=integer">Edit Port Setting</a>
+<a href="/settings#edit=port&type=integer&description=Server+port+number">Edit Port Setting</a>
 ```
 
 #### REST API

data/VERSION

@@ -1 +1 @@
-2.4.0
+2.4.1

data/lib/super_settings/application/helper.rb

@@ -76,6 +76,10 @@ module SuperSettings
 
     # Render an image tag for one of the SVG images in the images directory. If the :color option
     # is specified, it will be applied to the SVG image.
+    #
+    # @param name [String] the name of the icon to render
+    # @param options [Hash] options for the icon (style, color, etc.)
+    # @return [String] the HTML for the icon
     def icon_image(name, options = {})
       svg = ICON_SVG[name.to_s]
       style = (options[:style] || {})
@@ -91,6 +95,16 @@ module SuperSettings
     end
 
     # Render an icon image as a link tag.
+    #
+    # @param icon [String] the name of the icon to render
+    # @param title [String] the title/tooltip for the button
+    # @param color [String] the color for the icon
+    # @param js_class [String] CSS class for JavaScript behavior
+    # @param url [String] the URL for the link (optional)
+    # @param disabled [Boolean] whether the button is disabled
+    # @param style [Hash] CSS styles for the icon
+    # @param link_style [String] CSS styles for the link
+    # @return [String] the HTML for the icon button
     def icon_button(icon, title:, color:, js_class:, url: nil, disabled: false, style: {}, link_style: nil)
       url = "#" if Coerce.blank?(url)
       image = icon_image(icon, alt: title, style: ICON_BUTTON_STYLE.merge(style).merge(color: color))

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

@@ -43,7 +43,7 @@
     </div>
   </form>
 
-  <div id="super-settings-modal" class="super-settings-modal js-close-modal" aria-hidden="true" aria-role="dialog">
+  <div id="super-settings-modal" class="super-settings-modal js-close-modal" aria-hidden="true" role="dialog">
     <div class="super-settings-modal-dialog">
       <button type="button" title="Close Dialog" class="super-settings-modal-close super-settings-btn-no-chrome js-close-modal">&times;</button>
       <div class="super-settings-modal-content">

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

@@ -4,7 +4,7 @@
     <title><%= application_name %> Settings</title>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta name="pinterest" content="nopin" />
+    <meta name="pinterest" content="nopin">
     <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">

data/lib/super_settings/application/scripts.js

@@ -232,7 +232,7 @@
   }
 
   // Create a card with form elements for creating a new setting.
-  function newSettingCard(key, valueType) {
+  function newSettingCard(key, valueType, description) {
     if (!key) {
       key = "";
     }
@@ -240,7 +240,7 @@
       valueType = "string";
     }
     const randomId = "new" + Math.floor((Math.random() * 0xFFFFFFFFFFFFFF)).toString(16);
-    const setting = {id: randomId, key: key, value: "", value_type: valueType, new_record: true}
+    const setting = {id: randomId, key: key, value: "", value_type: valueType, description: description, new_record: true}
     card = editSettingCard(setting);
     return card;
   }
@@ -489,8 +489,8 @@
   }
 
   // Add a new setting.
-  function addSetting(key, valueType) {
-    const card = addCardToContainer(newSettingCard(key, valueType));
+  function addSetting(key, valueType, description) {
+    const card = addCardToContainer(newSettingCard(key, valueType, description));
     card.querySelector(".super-settings-card-key input").focus();
   }
 
@@ -722,7 +722,7 @@
     hashParams.split('&').forEach(function(param) {
       const [key, value] = param.split('=', 2);
       if (key && value) {
-        params[decodeURIComponent(key)] = decodeURIComponent(value);
+        params[decodeURIComponent(key)] = decodeURIComponent(value.replace(/\+/g, ' '));
       }
     });
 
@@ -886,7 +886,7 @@
         if (setting) {
           editSetting(setting);
         } else {
-          addSetting(hashParams.edit, hashParams.type);
+          addSetting(hashParams.edit, hashParams.type, hashParams.description);
         }
       }
       enableSaveButton();

data/lib/super_settings/application.rb

@@ -29,7 +29,7 @@ module SuperSettings
 
     # Render the web UI application HTML.
     #
-    # @return [void]
+    # @return [String] the rendered HTML
     def render
       template = ERB.new(File.read(File.expand_path(File.join("application", "index.html.erb"), __dir__)))
       html = template.result(binding)

data/lib/super_settings/coerce.rb

@@ -5,6 +5,7 @@ require "set"
 module SuperSettings
   # Utility functions for coercing values to other data types.
   class Coerce
+    # Set of values that should be considered false when converting to boolean.
     # rubocop:disable Lint/BooleanSymbol
     FALSE_VALUES = Set.new([
       "0", :"0",

data/lib/super_settings/context/current.rb

@@ -2,28 +2,51 @@
 
 module SuperSettings
   module Context
+    # Current context for maintaining consistent setting values and random numbers
+    # within a specific execution context.
     class Current
       def initialize
         @context = {}
         @seed = nil
       end
 
+      # Check if the context includes a specific key.
+      #
+      # @param key [String] the key to check
+      # @return [Boolean] true if the key exists in the context
       def include?(key)
         @context.include?(key)
       end
 
+      # Get a value from the context.
+      #
+      # @param key [String] the key to retrieve
+      # @return [Object] the value associated with the key
       def [](key)
         @context[key]
       end
 
+      # Set a value in the context.
+      #
+      # @param key [String] the key to set
+      # @param value [Object] the value to store
+      # @return [Object] the stored value
       def []=(key, value)
         @context[key] = value
       end
 
+      # Delete a value from the context.
+      #
+      # @param key [String] the key to delete
+      # @return [Object] the deleted value
       def delete(key)
         @context.delete(key)
       end
 
+      # Generate a consistent random number for this context.
+      #
+      # @param max [Integer, Float, Range] the maximum value or range
+      # @return [Integer, Float] the random number
       def rand(max = nil)
         @seed ||= Random.new_seed
         Random.new(@seed).rand(max || 1.0)

data/lib/super_settings/context.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module SuperSettings
+  # Context classes for maintaining consistent state during execution blocks.
+  # These contexts ensure that settings and random values remain constant
+  # within a specific execution scope.
   module Context
     autoload :Current, File.join(__dir__, "context/current")
     autoload :RackMiddleware, File.join(__dir__, "context/rack_middleware")

data/lib/super_settings/local_cache.rb

@@ -60,6 +60,7 @@ module SuperSettings
       end
 
       return nil if value == NOT_DEFINED
+
       value
     end
 
@@ -105,11 +106,15 @@ module SuperSettings
     end
 
     # Load all the settings from the database into the cache.
+    #
+    # @param asynchronous [Boolean] whether to load settings in a background thread
+    # @return [void]
     def load_settings(asynchronous = false)
       return if @refreshing
 
       @lock.synchronize do
         return if @refreshing
+
         @refreshing = true
         @next_check_at = Time.now + @refresh_interval
       end
@@ -135,6 +140,9 @@ module SuperSettings
     end
 
     # Load only settings that have changed since the last load.
+    #
+    # @param asynchronous [Boolean] whether to refresh settings in a background thread
+    # @return [void]
     def refresh(asynchronous = false)
       last_refresh_time = @last_refreshed
       return if last_refresh_time.nil?
@@ -142,8 +150,10 @@ module SuperSettings
 
       @lock.synchronize do
         return if @refreshing
+
         @next_check_at = Time.now + @refresh_interval
         return if @cache.empty?
+
         @refreshing = true
       end
 
@@ -166,6 +176,8 @@ module SuperSettings
     end
 
     # Reset the cache to an unloaded state.
+    #
+    # @return [void]
     def reset
       @lock.synchronize do
         @cache = {}.freeze
@@ -189,6 +201,7 @@ module SuperSettings
     # @api private
     def update_setting(setting)
       return if Coerce.blank?(setting.key)
+
       @lock.synchronize do
         @cache = @cache.merge(setting.key => setting.value)
       end
@@ -199,6 +212,7 @@ module SuperSettings
     def wait_for_load
       loop do
         return unless @refreshing
+
         sleep(0.001)
       end
     end

data/lib/super_settings/rack_application.rb

@@ -11,7 +11,7 @@ module SuperSettings
   #
   # You are also responsible for implementing any CSRF protection if your authentication method
   # uses stateful requests (i.e. cookies or Basic auth where browser automatically include the
-  # credentials on every reqeust). There are other gems available that can be integrated into
+  # credentials on every request). There are other gems available that can be integrated into
   # your middleware stack to provide this feature. If you need to inject meta elements into
   # the page, you can do so with the +add_to_head+ method.
   class RackApplication
@@ -225,8 +225,10 @@ module SuperSettings
     def check_authorization(request, write_required: false)
       user = current_user(request)
       return json_response(401, error: "Authentiation required") unless authenticated?(user)
+
       allowed = (write_required ? allow_write?(user) : allow_read?(user))
       return json_response(403, error: "Access denied") unless allowed
+
       yield(user)
     end
 

data/lib/super_settings/rest_api.rb

@@ -16,12 +16,14 @@ module SuperSettings
       #       key: string,
       #       value: object,
       #       value_type: string,
-      #       description string,
+      #       description: string,
       #       created_at: iso8601 string,
       #       updated_at: iso8601 string
       #     },
       #     ...
       #   ]
+      #
+      # @return [Hash] hash with settings array
       def index
         settings = Setting.active.reject(&:deleted?).sort_by(&:key)
         {settings: settings.collect(&:as_json)}
@@ -29,6 +31,7 @@ module SuperSettings
 
       # Get a setting by id.
       #
+      # @param key [String] setting key
       # @example
       #   GET /setting
       #
@@ -41,10 +44,12 @@ module SuperSettings
       #     key: string,
       #     value: object,
       #     value_type: string,
-      #     description string,
+      #     description: string,
       #     created_at: iso8601 string,
       #     updated_at: iso8601 string
       #   }
+      #
+      # @return [Hash, nil] setting hash or nil if not found
       def show(key)
         setting = Setting.find_by_key(key)
         setting.as_json if setting && !setting.deleted?
@@ -52,6 +57,8 @@ module SuperSettings
 
       # The update operation uses a transaction to atomically update all settings.
       #
+      # @param settings_params [Array] array of setting parameter hashes
+      # @param changed_by [String] identifier for who made the changes
       # @example
       #   POST /settings
       #
@@ -81,6 +88,8 @@ module SuperSettings
       #   or
       #
       #   {success: false, errors: {key => [string], ...}}
+      #
+      # @return [Hash] result hash with success status and any errors
       def update(settings_params, changed_by = nil)
         all_valid, settings = Setting.bulk_update(Array(settings_params), changed_by)
         if all_valid
@@ -98,6 +107,9 @@ module SuperSettings
 
       # Return the history of the setting.
       #
+      # @param key [String] setting key
+      # @param limit [Integer] number of history items to return
+      # @param offset [Integer] index to start fetching items from (most recent items are first)
       # @example
       #   GET /setting/history
       #
@@ -121,6 +133,8 @@ module SuperSettings
       #     previous_page_params: hash,
       #     next_page_params: hash
       #   }
+      #
+      # @return [Hash, nil] history hash or nil if setting not found
       def history(key, limit: nil, offset: 0)
         setting = Setting.find_by_key(key)
         return nil unless setting
@@ -162,12 +176,15 @@ module SuperSettings
       #   {
       #     last_updated_at: iso8601 string
       #   }
+      #
+      # @return [Hash] hash with the last updated timestamp
       def last_updated_at
         {last_updated_at: Setting.last_updated_at.utc.iso8601(6)}
       end
 
       # Return settings that have been updated since a specified timestamp.
       #
+      # @param time [Time, String] timestamp to check for updates since
       # @example
       #   GET /updated_since
       #
@@ -181,12 +198,14 @@ module SuperSettings
       #       key: string,
       #       value: object,
       #       value_type: string,
-      #       description string,
+      #       description: string,
       #       created_at: iso8601 string,
       #       updated_at: iso8601 string
       #     },
       #     ...
       #   ]
+      #
+      # @return [Hash] hash with settings array
       def updated_since(time)
         time = Coerce.time(time)
         settings = Setting.updated_since(time).reject(&:deleted?)

data/lib/super_settings/setting.rb

@@ -9,6 +9,7 @@ module SuperSettings
   # ships with storage engines for ActiveRecord, Redis, and HTTP (microservice). See the SuperSettings::Storage
   # class for more details.
   class Setting
+    # Cache key used for storing the last updated timestamp.
     LAST_UPDATED_CACHE_KEY = "SuperSettings.last_updated_at"
 
     STRING = "string"
@@ -266,6 +267,7 @@ module SuperSettings
           setting = changed[key] || Setting.find_by_key(key)
           unless setting
             next if Coerce.present?(setting_params["delete"])
+
             setting = Setting.new(key: setting_params["key"])
           end
 
@@ -545,6 +547,7 @@ module SuperSettings
 
     # Serialize to a hash that is used for rendering JSON responses.
     #
+    # @param options [Hash] options for JSON serialization (unused but maintained for compatibility)
     # @return [Hash]
     def as_json(options = nil)
       attributes = {
@@ -561,6 +564,7 @@ module SuperSettings
 
     # Serialize to a JSON string.
     #
+    # @param options [Hash] options to pass to JSON generation
     # @return [String]
     def to_json(options = nil)
       as_json.to_json(options)

data/lib/super_settings/storage/http_storage.rb

@@ -35,15 +35,13 @@ module SuperSettings
         # Add headers to this hash to add them to all requests to the SuperSettings REST API.
         #
         # @example
-        #
-        # SuperSettings::HttpStorage.headers["Authorization"] = "Bearer 12345"
+        #   SuperSettings::HttpStorage.headers["Authorization"] = "Bearer 12345"
         attr_reader :headers
 
         # Add query parameters to this hash to add them to all requests to the SuperSettings REST API.
         #
         # @example
-        #
-        # SuperSettings::HttpStorage.query_params["access_token"] = "12345"
+        #   SuperSettings::HttpStorage.query_params["access_token"] = "12345"
         attr_reader :query_params
 
         def all

data/lib/super_settings/storage/redis_storage.rb

@@ -35,6 +35,7 @@ module SuperSettings
           def find_all_by_key(key:, offset: 0, limit: nil)
             end_index = (limit.nil? ? -1 : offset + limit - 1)
             return [] unless end_index >= -1
+
             payloads = RedisStorage.with_redis { |redis| redis.lrange("#{HISTORY_KEY_PREFIX}.#{key}", offset, end_index) }
             payloads.collect do |json|
               record = new(JSON.parse(json))
@@ -112,6 +113,7 @@ module SuperSettings
         def find_by_key(key)
           json = with_redis { |redis| redis.hget(SETTINGS_KEY, key) }
           return nil unless json
+
           record = load_from_json(json)
           record unless record.deleted?
         end
@@ -123,6 +125,7 @@ module SuperSettings
         def last_updated_at
           result = with_redis { |redis| redis.zrevrange(UPDATED_KEY, 0, 1, withscores: true).first }
           return nil unless result
+
           time_at_microseconds(result[1])
         end
 

data/lib/super_settings/storage/test_storage.rb

@@ -50,6 +50,7 @@ module SuperSettings
         def find_by_key(key)
           attributes = settings[key]
           return nil unless attributes
+
           setting = new(attributes)
           setting.send(:set_persisted!)
           setting unless setting.deleted?

data/lib/super_settings/time_precision.rb

@@ -4,24 +4,42 @@ module SuperSettings
   # Helper class for truncating timestamps to a specific precision. This is used by storage engines
   # to ensure that timestamps are stored and compared with the same precision.
   class TimePrecision
+    # The time value with applied precision.
     attr_reader :time
 
+    # Create a new TimePrecision object.
+    #
+    # @param time [Time, Numeric] the time to apply precision to
+    # @param precision [Symbol] the precision level (:microsecond or :millisecond)
+    # @raise [ArgumentError] if precision is not valid
     def initialize(time, precision = :microsecond)
       raise ArgumentError.new("Invalid precision: #{precision}") unless valid_precision?(precision)
 
       @time = time_with_precision(time.to_f, precision) if time
     end
 
+    # Convert the time to a float.
+    #
+    # @return [Float] the time as a floating point number
     def to_f
       @time.to_f
     end
 
     private
 
+    # Check if the precision value is valid.
+    #
+    # @param precision [Symbol] the precision to validate
+    # @return [Boolean] true if precision is valid
     def valid_precision?(precision)
       [:microsecond, :millisecond].include?(precision)
     end
 
+    # Apply the specified precision to a timestamp.
+    #
+    # @param timestamp [Float] the timestamp to apply precision to
+    # @param precision [Symbol] the precision level
+    # @return [Time] the time with applied precision
     def time_with_precision(timestamp, precision)
       usec = (timestamp % 1) * 1_000_000.0
       if precision == :millisecond

data/lib/super_settings.rb

@@ -23,6 +23,7 @@ module SuperSettings
   autoload :HttpClient, "super_settings/http_client"
   autoload :VERSION, "super_settings/version"
 
+  # Default number of seconds between cache refresh checks.
   DEFAULT_REFRESH_INTERVAL = 5.0
 
   @local_cache = LocalCache.new(refresh_interval: DEFAULT_REFRESH_INTERVAL)
@@ -41,7 +42,7 @@ module SuperSettings
       Coerce.string(val)
     end
 
-    # Alias for {#get} to allow using the [] operator to get a setting value.
+    # Alias for {.get} to allow using the [] operator to get a setting value.
     #
     # @param key [String, Symbol]
     # @return [String]
@@ -107,6 +108,7 @@ module SuperSettings
       val = context_setting(key)
       val = default if val.nil?
       return nil if val.nil?
+
       Array(val).collect { |v| v&.to_s }
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: super_settings
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.4.1
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-22 00:00:00.000000000 Z
+date: 2025-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler