glib-web 6.10.1 → 6.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50357c0c3002870707a68fad3a956248fb13cfb638395068ab970c0a7ee930ed
-  data.tar.gz: d04d1755a167f4d46c18aec66c958050c324192ee847b0ab0ed930ffd7ab2f7e
+  metadata.gz: 4466ade33c7e7109a75befa19d22951379a4b57f0c20608b26ba80a9e539901b
+  data.tar.gz: 9d05610c2feda72d878a64a44dec1f3cf8aa48c7f9237d2b3ce769d89beb9c8a
 SHA512:
-  metadata.gz: b72912d4e0dbe1fceb6d2180c292c390567a1c0d5ccc8e5f80bd20fa579d48b87cb0455a7ea3849469e24fbdb6ca90d5059e4c2799de0e0ab0dd15aa3c1e9430
-  data.tar.gz: fd855eb185f11b6d6e73becf6ab91ef1de85c78e957ae653e6f7a6e6bc9cb07eaa869f5f01142d8e73f674553dc621c4ebc517ce1b8bb4f76359a1571ca5bb60
+  metadata.gz: b2bbafdaaa9ddc994cafe76cc6520a3b8b7dd07e0ae456d666fe62ec061efd8f854f3e719d297d39146e6c0f259c80074f5b28655e2f898b5dbdc2ae243eb4aa
+  data.tar.gz: aed913d8a8aeb19d81e0b01bde95480efe12ddbec54acd2095aed02fcb05e2753d57068c586faba341a2e6f282be41ec9b0e353951e881b853130e292d5a4ddd

data/app/helpers/glib/json_ui/view_builder/fields.rb

@@ -211,6 +211,51 @@ class Glib::JsonUi::ViewBuilder
       end
     end
 
+    # Timing options for the `onChange` / `onChangeAndLoad` actions of fields
+    # whose value changes while the user is still typing.
+    #
+    # Honoured by the single-line text family (text, number, email, url,
+    # password -- all one Vue component) and by textarea. Other fields ignore
+    # them: the discrete ones (check, radio, select, chip group, date pickers)
+    # commit a value the moment it is picked, and richText/phone/file keep
+    # their own reporting. The options are declared on `Text`, so its other
+    # subclasses accept them without effect -- same as `leftIcon` and
+    # `onTypeStart` there.
+    #
+    # In both modes the change is also reported when focus leaves the field.
+    # Under `input` that only flushes a change already pending in the debounce
+    # window -- it cannot produce a second run, because a value that was
+    # already reported is not reported again.
+    module ChangeTrigger
+      def self.included(base)
+        # When the `onChange` / `onChangeAndLoad` actions fire.
+        #
+        # - `input` (default): after the user pauses typing for `changeDelay`.
+        # - `blur`: only once focus leaves the field. Use for actions too
+        #   expensive to run mid-word -- a server round trip, a recalculation
+        #   that rewrites other fields under the user's cursor.
+        #
+        # @example Round-trip only once the user is done with the field
+        #   form.fields_text \
+        #     name: 'user[promo_code]',
+        #     label: 'Promo code',
+        #     changeOn: 'blur',
+        #     onChange: ->(action) { action.http_get url: verify_promo_path }
+        base.enum :changeOn, options: %w[input blur]
+
+        # Milliseconds of no typing before `changeOn: 'input'` fires.
+        # Defaults to 300. Ignored under `changeOn: 'blur'`.
+        #
+        # @example Slow down a search-as-you-type round trip
+        #   form.fields_text \
+        #     name: 'q',
+        #     label: 'Search',
+        #     changeDelay: 800,
+        #     onChange: ->(action) { action.http_get url: search_path }
+        base.int :changeDelay
+      end
+    end
+
     # Basic text input field for single-line text entry.
     #
     # The most common field type, supporting various customizations like
@@ -228,6 +273,8 @@ class Glib::JsonUi::ViewBuilder
     #
     # @see app/views/json_ui/garage/forms/basic.json.jbuilder Garage example
     class Text < AbstractField
+      include ChangeTrigger
+
       # Maximum number of characters allowed.
       int :maxLength
 
@@ -909,23 +956,41 @@ class Glib::JsonUi::ViewBuilder
     #     width: 220,
     #     height: 100
     #
-    # @note The field deliberately has no pre-populated value: a saved
-    #   signature is a signed id that cannot be redrawn from the canvas.
-    #   Resize it via `components_set`/`logics_set` with `width`/`height`.
+    # @note A saved signature is a signed id that cannot be redrawn from the
+    #   canvas: when a record is re-edited the field pre-populates `value`
+    #   with the existing attachment's signed id (the component renders a
+    #   read-only preview instead of ink). An untouched field therefore
+    #   re-submits that same signed id, so consumers should treat a
+    #   same-signed-id re-attach as "no change". Resize it via
+    #   `components_set`/`logics_set` with `width`/`height`.
     #
     # @see app/views/json_ui/garage/test_page/fields_sign.json.jbuilder Garage examples
     class Sign < AbstractField
       string :directUploadUrl
       required :directUploadUrl
 
-      # Enables the Type tab. `name` is the param the typed name is submitted
-      # under; `value` pre-populates it; `label`/`placeholder` decorate the
-      # text input in the dialog.
-      hash :typedName, required: [:name], optional: [:value, :label, :placeholder]
+      # URL of an already-attached signature image to display as a read-only
+      # preview (typically `file_url(attachment)` when re-editing a record
+      # that has a drawn signature). Pair with `prop:` so the field also
+      # submits the existing signed id when left untouched.
+      string :fileUrl
+
+      # Enables the Type tab. `value` pre-populates the previously typed
+      # name; `label`/`placeholder` decorate the text input in the dialog.
+      # `name` is still accepted but unused: the typed name is submitted
+      # through the field's own param (single-param contract), and the
+      # server routes it to the name attribute.
+      hash :typedName, optional: [:name, :value, :label, :placeholder]
 
       # Override
-      # Signature field doesn't have default value
-      def value(value)
+      # A stored signature is an attachment -- submit its signed id (mirrors
+      # File#determine_value) so re-editing a signed submission pre-fills the
+      # field with the existing blob's signed id instead of serializing the
+      # whole attachment proxy.
+      def determine_value(context, prop)
+        if (value = context.field_value(prop)).attached?
+          value.signed_id || ''
+        end
       end
     end
 

data/app/jobs/glib/purge_unattached_job.rb

@@ -6,17 +6,21 @@ module Glib
   # Opt-in: if the host app has not run the gem's `create_snapshot_blob_references` migration,
   # `SnapshotBlobReference.table_exists?` is false and the exclusion subquery short-circuits —
   # the job then behaves identically to Rails' built-in unattached-blob cleanup, just delayed
-  # by 8 hours to give upload flows time to attach.
+  # by `Glib::PurgeUnattached::Config.min_age` (8 hours by default) to give upload flows time
+  # to attach.
   #
   # Schedule from the host app (e.g. via sidekiq-cron):
   #   Glib::PurgeUnattachedJob.perform_later
+  #
+  # Adjust the grace window from the host app (e.g. for a slower upload flow):
+  #   Glib::PurgeUnattached::Config.min_age = 10.hours
   class PurgeUnattachedJob < ApplicationJob
     queue_as :cleanup
 
     def perform(*_args)
       scope = ActiveStorage::Blob
         .unattached
-        .where('active_storage_blobs.created_at < ?', 8.hours.ago)
+        .where('active_storage_blobs.created_at < ?', Glib::PurgeUnattached::Config.min_age.ago)
 
       if SnapshotBlobReference.table_exists?
         scope = scope.where.not(id: SnapshotBlobReference.select(:blob_id))

data/app/models/concerns/glib/snapshot_v2.rb

@@ -10,6 +10,24 @@ require 'hashdiff'
 #   2. Nil has_one safe-nav in check_snapshot_changed.
 #   3. has_one wrapping in diff_associations (V2 only tested with has_many in mapping-web).
 #   4. ActiveStorage in diff_associations (convert Attached::One/Many to attachment records).
+#   5. same_as_before? derives from the computed diff instead of the instance-local
+#      `snapshot_changed` flag (mapping-web's flag-gating silently dropped a target's
+#      snapshot when taken after the owner's -- see "Snapshot ordering" below, issue #481).
+#
+# ## Snapshot ordering: owner vs association targets
+#
+# Owner and association-target snapshots may be taken in ANY order within a request.
+# `same_as_before?` decides from persisted state, so a target snapshotted after its owner
+# (through the replaced association target) still records its version.
+#
+# The one residual ordering caveat: `diff` compares against the instance's IN-MEMORY
+# attributes, so unsaved changes live only on the instance that holds them. If a target is
+# modified in memory without saving, snapshot it via a local captured BEFORE the owner's
+# `glib_create_snapshot!` (whose `with_lock` reload replaces the association targets) --
+# reading the target back through the association snapshots the persisted state instead.
+#
+# `snapshot_changed` / `attributes_before_save` remain writable instance accessors for
+# call-site use, but they are no longer consulted for the skip decision.
 #
 # To get all records of a model, you can use the following query:
 # MyModel.joins(:snapshots).distinct
@@ -106,8 +124,9 @@ module Glib
                 metadata: {} # Keep for potential future use, but main data in columns
               }
 
-              # Don't create version if same as before
-              unless same_as_before?
+              # Don't create version if same as before. Reuses `calculated_diff` instead of
+              # recomputing it inside `same_as_before?`.
+              unless same_as_before?(calculated_diff)
                 # No nil guard: active_snapshot's `create_snapshot!` raises on failure and
                 # always returns the snapshot.
                 snapshot = create_snapshot!(**snapshot_obj)
@@ -166,10 +185,14 @@ module Glib
       snapshots.order(version: :desc).first
     end
 
-    def same_as_before?
-      return !snapshot_changed if snapshot_prev.blank?
-
-      computed_diff = diff
+    # Decides whether `glib_create_snapshot!` should skip the version write. Derived from
+    # the computed diff (persisted state), never from the instance-local `snapshot_changed`
+    # flag: the flag dies with its instance, and an owner's snapshot replaces association
+    # targets with fresh instances (`with_lock`'s reload clears the association cache, then
+    # the diff walk re-reads the targets), so flag-gating used to silently drop a target's
+    # follow-up snapshot taken through the association (issue #481). For a first snapshot
+    # (no previous version) the diff runs current state against `attributes_before_save || {}`.
+    def same_as_before?(computed_diff = diff)
       item_unchanged = computed_diff['item'].blank?
       assoc_diff = computed_diff['associations']
       associations_unchanged = assoc_diff.nil? || assoc_diff.values.all?(&:blank?)

data/app/views/json_ui/garage/test_page/_header.json.jbuilder

@@ -37,6 +37,7 @@ nav_groups = {
     'fields_stripeExternalAccount',
     'fields_creditCard',
     'fields_timer',
+    'fields_change_trigger',
     'fields_upload',
     'fields_url_fragment',
     'fields_captcha',

data/app/views/json_ui/garage/test_page/fields_change_trigger.json.jbuilder

@@ -0,0 +1,128 @@
+json.title 'Test Page (Fields Change Trigger)'
+
+page = json_ui_page json
+
+render 'json_ui/garage/test_page/header', json: json, page: page
+
+page.body(
+  childViews: ->(body) do
+
+    body.panels_responsive(
+      padding: glib_json_padding_body,
+      childViews: ->(res) do
+        res.h2 text: 'Fields Change Trigger'
+        res.spacer height: 8
+        res.label text: 'changeOn / changeDelay control WHEN a typed-input field reports its change to onChange.'
+        res.spacer height: 12
+
+        res.panels_form(
+          url: json_ui_garage_url(path: 'forms/generic_post'),
+          method: 'post',
+          childViews: ->(form) do
+
+            # ── Default: changeOn 'input', 300ms ──────────────────────────────
+            form.h4 text: 'Default (changeOn: input)'
+            form.spacer height: 8
+            form.label text: 'No options set: reports once the user pauses for the default 300ms.'
+            form.spacer height: 8
+
+            form.fields_text(
+              name: 'user[default_value]',
+              label: 'Default',
+              placeholder: 'default',
+              width: 'matchParent',
+              onChange: ->(action) do
+                action.logics_set(
+                  targetId: 'status_default',
+                  conditionalData: { text: { 'printf': ['Default: {0}', { 'var': 'user[default_value]' }] } }
+                )
+              end
+            )
+            form.spacer height: 8
+            form.label id: 'status_default', text: 'Default: idle'
+
+            form.spacer height: 12
+            form.hr width: 'matchParent'
+            form.spacer height: 12
+
+            # ── changeDelay ───────────────────────────────────────────────────
+            form.h4 text: 'changeDelay: 1500'
+            form.spacer height: 8
+            form.label text: 'Same input mode, longer pause. Leaving the field still reports right away, rather than waiting out the remaining delay.'
+            form.spacer height: 8
+
+            form.fields_text(
+              name: 'user[slow]',
+              label: 'Slow',
+              placeholder: 'slow',
+              width: 'matchParent',
+              changeDelay: 1500,
+              onChange: ->(action) do
+                action.logics_set(
+                  targetId: 'status_slow',
+                  conditionalData: { text: { 'printf': ['Slow: {0}', { 'var': 'user[slow]' }] } }
+                )
+              end
+            )
+            form.spacer height: 8
+            form.label id: 'status_slow', text: 'Slow: idle'
+
+            form.spacer height: 12
+            form.hr width: 'matchParent'
+            form.spacer height: 12
+
+            # ── changeOn: 'blur' ──────────────────────────────────────────────
+            form.h4 text: "changeOn: 'blur'"
+            form.spacer height: 8
+            form.label text: 'Stays idle no matter how long the user pauses; reports only once focus leaves.'
+            form.spacer height: 8
+
+            form.fields_text(
+              name: 'user[on_blur]',
+              label: 'Reports on blur',
+              placeholder: 'on blur',
+              width: 'matchParent',
+              changeOn: 'blur',
+              onChange: ->(action) do
+                action.logics_set(
+                  targetId: 'status_on_blur',
+                  conditionalData: { text: { 'printf': ['Blur: {0}', { 'var': 'user[on_blur]' }] } }
+                )
+              end
+            )
+            form.spacer height: 8
+            form.label id: 'status_on_blur', text: 'Blur: idle'
+
+            form.spacer height: 12
+            form.hr width: 'matchParent'
+            form.spacer height: 12
+
+            # ── Textarea on blur ──────────────────────────────────────────────
+            form.h4 text: "fields_textarea with changeOn: 'blur'"
+            form.spacer height: 8
+
+            form.fields_textarea(
+              name: 'user[notes]',
+              label: 'Notes',
+              placeholder: 'notes',
+              width: 'matchParent',
+              rows: 3,
+              changeOn: 'blur',
+              onChange: ->(action) do
+                action.logics_set(
+                  targetId: 'status_notes',
+                  conditionalData: { text: { 'printf': ['Notes: {0}', { 'var': 'user[notes]' }] } }
+                )
+              end
+            )
+            form.spacer height: 8
+            form.label id: 'status_notes', text: 'Notes: idle'
+
+            form.spacer height: 16
+            form.fields_submit text: 'Submit'
+          end
+        )
+      end
+    )
+  end
+)

data/app/views/json_ui/garage/test_page/fields_sign.json.jbuilder

@@ -1,5 +1,8 @@
 json.title 'Test Page (Fields Sign)'
 
+# 60x20 ink stand-in used by the pre-filled examples.
+preview_data_uri = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADwAAAAUCAYAAADRA14pAAAAoklEQVR4nO2XUQrAIAxDcwjvf9WNfQzG1NFqUt1mwL8a8hBtxfYzYXSAaC1glVJK2RohOXAJdCS4FNgCGw0tA7YAjQCXAHsBoqAPbzpwa3A19OkLpjkjsAL66gmWOTOo0gtvOJXe/VcP9JpH3DvmewBLkdeUKfaLD09xqSaid7bkqilrS57pKHJCYmWq9uFZQD2ZLLkeB49ZQO/qybX+w1/XDujJvn2bufeCAAAAAElFTkSuQmCC'
+
 page = json_ui_page json
 
 render 'json_ui/garage/test_page/header', json: json, page: page
@@ -26,7 +29,10 @@ page.body(
               id: 'signature_main',
               name: 'user[signature]',
               label: 'Your signature',
-              typedName: { name: 'user[signature_name]', label: 'Type your full name', placeholder: 'Full name' },
+              # Single-param contract: the typed name is submitted through the
+              # field's own param, so typedName carries only the input's
+              # decoration and pre-filled value.
+              typedName: { label: 'Type your full name', placeholder: 'Full name' },
               directUploadUrl: glib_direct_uploads_url,
               width: 320,
               height: 160,
@@ -148,6 +154,46 @@ page.body(
               width: 220,
               height: 100
             )
+
+            form.spacer height: 12
+            form.hr width: 'matchParent'
+            form.spacer height: 12
+
+            form.h2 text: 'Pre-filled (re-edit)'
+            form.spacer height: 8
+            form.label text: 'A saved signature: value carries the signed id, fileUrl renders the preview.'
+            form.spacer height: 8
+            form.fields_sign(
+              id: 'signature_prefilled',
+              name: 'user[signature_prefilled]',
+              # A stand-in for the signed id the Sign builder derives from
+              # `prop:` on a re-edit (see Sign#determine_value).
+              value: 'prefilled-signed-id',
+              fileUrl: preview_data_uri,
+              typedName: { label: 'Type your full name', placeholder: 'Full name' },
+              directUploadUrl: glib_direct_uploads_url,
+              width: 320,
+              height: 160
+            )
+
+            form.spacer height: 12
+            form.hr width: 'matchParent'
+            form.spacer height: 12
+
+            form.h2 text: 'Read-only (pre-filled)'
+            form.spacer height: 8
+            form.label text: 'A saved signature on a read-only field: the preview shows, the edit overlay does not.'
+            form.spacer height: 8
+            form.fields_sign(
+              id: 'signature_readonly',
+              name: 'user[signature_readonly]',
+              value: 'readonly-signed-id',
+              fileUrl: preview_data_uri,
+              directUploadUrl: glib_direct_uploads_url,
+              width: 320,
+              height: 160,
+              readOnly: true
+            )
           end
         )
       end

data/lib/glib/purge_unattached/config.rb

@@ -0,0 +1,38 @@
+require 'active_support/core_ext/numeric/time'
+
+module Glib
+  module PurgeUnattached
+    # Global settings for Glib::PurgeUnattachedJob.
+    #
+    # `min_age` is how long an unattached ActiveStorage blob must exist before
+    # the purge may remove it. The 8-hour default leaves room for multi-step
+    # upload flows (direct upload -> form submit -> attach) to finish before
+    # their blob becomes eligible; apps with slower flows raise it:
+    #
+    #   # config/initializers/glib.rb
+    #   Glib::PurgeUnattached::Config.min_age = 10.hours
+    #
+    # Deliberately NOT a setting on the job class: the job is autoloaded from
+    # app/, so an initializer-assigned value would be wiped the first time the
+    # class is reloaded. This file lives in lib/ and is required eagerly by
+    # glib-web.rb, which is what makes the setting survive reloads.
+    class Config
+      # The shipped default. Apps opt into a different window via the setter.
+      DEFAULT_MIN_AGE = 8.hours
+
+      @@min_age = DEFAULT_MIN_AGE
+
+      def self.min_age
+        @@min_age
+      end
+
+      def self.min_age=(value)
+        unless value.is_a?(ActiveSupport::Duration) && value.positive?
+          raise ArgumentError, "Invalid min_age: #{value.inspect}. Expected a positive ActiveSupport::Duration (e.g. 10.hours)."
+        end
+
+        @@min_age = value
+      end
+    end
+  end
+end

data/lib/glib-web.rb

@@ -6,10 +6,12 @@ if defined?(::Rails)
 end
 require 'glib/value'
 # Loaded eagerly (not autoloaded from app/) so an app initializer can set
-# `Glib::JsonUi::Config.name_separator` without tripping Rails' ban on
-# autoloading during initialization -- and so the setting survives a reload.
+# `Glib::JsonUi::Config.name_separator` or `Glib::PurgeUnattached::Config.min_age`
+# without tripping Rails' ban on autoloading during initialization -- and so the
+# setting survives a reload.
 require 'glib/json_ui/config'
 require 'glib/json_ui/name'
+require 'glib/purge_unattached/config'
 require 'glib/json_crawler'
 
 require 'glib/dynamic_text'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glib-web
 version: !ruby/object:Gem::Version
-  version: 6.10.1
+  version: 6.10.3
 platform: ruby
 authors:
 - ''
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -456,6 +456,7 @@ files:
 - app/views/json_ui/garage/test_page/duplicate_names.json.jbuilder
 - app/views/json_ui/garage/test_page/fields.json.jbuilder
 - app/views/json_ui/garage/test_page/fields_captcha.json.jbuilder
+- app/views/json_ui/garage/test_page/fields_change_trigger.json.jbuilder
 - app/views/json_ui/garage/test_page/fields_creditCard.json.jbuilder
 - app/views/json_ui/garage/test_page/fields_date_time.json.jbuilder
 - app/views/json_ui/garage/test_page/fields_dynamicSelect.json.jbuilder
@@ -590,6 +591,7 @@ files:
 - lib/glib/last_resort_unit_test.rb
 - lib/glib/mailer_tester.rb
 - lib/glib/non_http_integration_test.rb
+- lib/glib/purge_unattached/config.rb
 - lib/glib/rubocop.rb
 - lib/glib/rubocop/cops/json_ui/base_nested_parameter.rb
 - lib/glib/rubocop/cops/json_ui/nested_action_parameter.rb