Extract reusable composite_control_editor<T>, fix fade freeze, add focus-loss shortcut

New common/composite-control-editor.h: composite_control_editor<T> encapsulates the
touch/fade/reset-on-retouch/hard-commit-on-lapse state machine previously hardcoded for
MinZ, so any other multi-param composite option can reuse it by holding its own
composite_control_editor<its-struct-type> instead of re-implementing the mechanism.
embedded_filter_model now holds one _minz_editor member of this type instead of four
separate fields; draw_minz_control_editor()/embedded_filter_enable_disable()/
populate_options() updated accordingly.

Fixes a real bug found by testing: the fill-color fade was capped at 25% progress and
then froze there for the rest of the 1.7s window before jumping to idle - looked like a
stall, not an animation. Fade now tracks the full window uncapped, same as the border
width gradient (400% -> 250%). Fill color is now gold/yellow fading toward the border's
own blue (ImGuiCol_FrameBgHovered) rather than toward the panel background.

Adds a focus-loss shortcut: if some OTHER widget elsewhere becomes active while this
group is dirty (not just "nothing is active", which is also true during the normal gap
between finishing one field and touching the next one in this group), finish the
countdown immediately instead of making the user wait out the rest of it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Evgeni Raikhel

common/CMakeLists.txt

@@ -75,6 +75,7 @@ set(COMMON_SRC
     "${CMAKE_CURRENT_LIST_DIR}/hdr-model.h"
     "${CMAKE_CURRENT_LIST_DIR}/hdr-model.cpp"
     "${CMAKE_CURRENT_LIST_DIR}/embedded-filter-model.h"
+    "${CMAKE_CURRENT_LIST_DIR}/composite-control-editor.h"
     "${CMAKE_CURRENT_LIST_DIR}/embedded-filter-model.cpp"
     "${CMAKE_CURRENT_LIST_DIR}/textual-icons.h"
     )

common/composite-control-editor.h

@@ -0,0 +1,186 @@
+// License: Apache 2.0. See LICENSE file in root directory.
+// Copyright(c) 2026 RealSense, Inc. All Rights Reserved.
+
+#pragma once
+
+#include <librealsense2/rs.hpp>
+#include <imgui.h>
+
+#include <algorithm>
+#include <limits>
+#include <memory>
+#include <string>
+
+namespace rs2
+{
+    // PROTOTYPE / DEMO: reusable debounced-auto-commit editor for a composite option's local
+    // struct T. Extracted from the original HKR MinZ Control implementation so any other
+    // multi-param composite option can get the same behavior - touch -> fade in -> reset on
+    // retouch -> hard commit on lapse - by holding one of these instead of re-implementing the
+    // mechanism. See embedded_filter_model::draw_minz_control_editor() for the reference usage.
+    //
+    // The whole framed group is treated as ONE editing unit, matching T being one atomic
+    // multi-field struct sent in a single UVC transaction - there is no per-field Send.
+    //
+    // Per-frame usage:
+    //   1. ensure_initialized(filter, id, error_message) - seeds `value` from a GET, once.
+    //   2. Draw the control-specific widgets against `value`. For each one:
+    //        - call touch() on every change while the edit is in progress (e.g. every tick of a
+    //          slider drag) - this flags the group dirty and defers any pending commit;
+    //        - call finalize() once that field's edit is done (slider release via
+    //          ImGui::IsItemDeactivatedAfterEdit(), or immediately after a checkbox/radio click,
+    //          which has no drag phase so touch+finalize happen together) - this (re)schedules
+    //          the real auto-commit `commit_delay` seconds out.
+    //   3. end_frame_and_maybe_commit(filter, id, error_message, frame_min, frame_max,
+    //      any_field_active_this_frame) - draws the fading fill + shrinking border around the
+    //      widgets' bounding box (continuously, for the full commit_delay window - no early
+    //      freeze), shows the hover tooltip, and sends `value` to the device in one atomic write
+    //      once the debounce timer has lapsed with no further touch() calls. `any_field_active_
+    //      this_frame` is true if any of THIS control's own widgets is the one currently active
+    //      (mid-drag/mid-click) - pass false once focus has genuinely left the group (some OTHER
+    //      widget elsewhere is now active) to finish the countdown immediately instead of making
+    //      the user wait it out.
+    template< typename T >
+    class composite_control_editor
+    {
+    public:
+        T value{};
+        bool initialized = false;
+
+        // Seeds `value` from a real GET the first time this is called; a no-op afterward. Returns
+        // whether `value` is safe to use (false only if the initial GET failed).
+        bool ensure_initialized( const std::shared_ptr< rs2::embedded_filter > & filter,
+                                  rs2_composite_option_id id,
+                                  std::string & error_message )
+        {
+            if( initialized )
+                return true;
+            try
+            {
+                value = filter->get_composite_option_as< T >( id );
+                initialized = true;
+            }
+            catch( const std::exception & e )
+            {
+                error_message = e.what();
+            }
+            return initialized;
+        }
+
+        // Call while a field is actively being changed (every tick of a slider drag, or a
+        // checkbox/radio click). Flags the group dirty and parks the deadline at +infinity so
+        // nothing commits mid-edit.
+        void touch()
+        {
+            _dirty = true;
+            _commit_deadline = std::numeric_limits< double >::max();
+        }
+
+        // Call once a field's edit is finalized (slider released, or immediately after a
+        // checkbox/radio click). Schedules the real auto-commit commit_delay seconds out.
+        void finalize() { _commit_deadline = ImGui::GetTime() + commit_delay; }
+
+        // Draws the dirty-state fill/border for [frame_min, frame_max] - call after drawing this
+        // control's own fields, once their bounding box is known - and sends `value` to the
+        // device in one atomic write if the debounce timer has lapsed since the last touch().
+        void end_frame_and_maybe_commit( const std::shared_ptr< rs2::embedded_filter > & filter,
+                                          rs2_composite_option_id id,
+                                          std::string & error_message,
+                                          const ImVec2 & frame_min,
+                                          const ImVec2 & frame_max,
+                                          bool any_field_active_this_frame )
+        {
+            constexpr float base_border_thickness = 1.0f;
+            float border_thickness = base_border_thickness;
+
+            // While actively being edited (deadline parked at +infinity by touch()) the fill and
+            // border sit at their starting intensity: 0% faded (bright gold), 400% border width.
+            // Once a countdown is actually running (finalize() set a real deadline), both fade
+            // smoothly over the ENTIRE commit_delay window, right up until the instant the commit
+            // fires below - no early cap/freeze partway through, or the animation visibly stalls
+            // for the remainder of the wait, which reads as a bug rather than a fade. The fill
+            // cools from gold toward the border's own blue (ImGuiCol_FrameBgHovered - the same
+            // color the border is drawn in, so the fill settles into harmony with it rather than
+            // into the panel background); the border shrinks from 400% down to 250% of normal.
+            // The commit itself then snaps both back to their plain idle look (no fill, 100%
+            // border) in one abrupt jump rather than continuing the gentle fade, so the moment
+            // something was actually sent reads as a distinct, more pronounced change than the
+            // animation leading up to it.
+            if( _dirty )
+            {
+                double remaining = _commit_deadline - ImGui::GetTime();
+                double frac_remaining = std::min( std::max( remaining / commit_delay, 0.0 ), 1.0 );
+                float progress = static_cast< float >( 1.0 - frac_remaining );   // 0 = just started, 1 = about to fire
+                float fade_t = progress;   // uncapped - tracks the full window, same as border_thickness below
+
+                ImVec4 start_color( 255.f / 255.f, 210.f / 255.f, 40.f / 255.f, 90.f / 255.f );   // bright gold/yellow
+                start_color.x = std::min( start_color.x * initial_brightness, 1.0f );
+                start_color.y = std::min( start_color.y * initial_brightness, 1.0f );
+                start_color.z = std::min( start_color.z * initial_brightness, 1.0f );
+                const ImVec4 target_blue = ImGui::GetStyle().Colors[ImGuiCol_FrameBgHovered];
+                ImVec4 blended(
+                    start_color.x + ( target_blue.x - start_color.x ) * fade_t,
+                    start_color.y + ( target_blue.y - start_color.y ) * fade_t,
+                    start_color.z + ( target_blue.z - start_color.z ) * fade_t,
+                    start_color.w + ( target_blue.w - start_color.w ) * fade_t );
+
+                ImGui::GetWindowDrawList()->AddRectFilled( frame_min, frame_max, ImGui::ColorConvertFloat4ToU32( blended ), 3.0f );
+                border_thickness = base_border_thickness * ( border_start_scale + ( border_end_scale - border_start_scale ) * progress );
+            }
+
+            ImGui::GetWindowDrawList()->AddRect(
+                frame_min, frame_max,
+                ImGui::GetColorU32( ImGuiCol_FrameBgHovered ),
+                3.0f,    // rounding
+                0,       // flags
+                border_thickness );
+
+            if( ImGui::IsMouseHoveringRect( frame_min, frame_max ) )
+            {
+                try
+                {
+                    ImGui::SetTooltip( "%s", filter->get_composite_option_description( id ) );
+                }
+                catch( const std::exception & )
+                {
+                    // Best-effort tooltip only - a failure here shouldn't disrupt the editor.
+                }
+            }
+
+            // Shortcut: focus genuinely left the group - some OTHER widget elsewhere is active
+            // this frame, not just "nothing is active right now" (which is also true during the
+            // normal quiet gap between finishing one field and touching the next one in THIS
+            // group, and must NOT cut the wait short). When that happens, don't make the user
+            // wait out the rest of the countdown - finish it now, same as if it had lapsed
+            // naturally.
+            if( _dirty && ! any_field_active_this_frame && ImGui::IsAnyItemActive() )
+                _commit_deadline = ImGui::GetTime();
+
+            // Fires once the countdown elapses quietly - checked every frame, so any fresh
+            // touch() (which re-parks the deadline at +infinity) naturally defers this for as
+            // long as the user keeps adjusting fields.
+            if( _dirty && ImGui::GetTime() >= _commit_deadline )
+            {
+                try
+                {
+                    filter->set_composite_option_from( id, value );
+                }
+                catch( const std::exception & e )
+                {
+                    error_message = e.what();
+                }
+                _dirty = false;
+                _commit_deadline = std::numeric_limits< double >::max();
+            }
+        }
+
+    private:
+        bool _dirty = false;
+        double _commit_deadline = std::numeric_limits< double >::max();
+
+        static constexpr double commit_delay = 1.7;          // seconds of quiet before auto-sending
+        static constexpr float initial_brightness = 1.2f;    // "under change" color, 20% brighter
+        static constexpr float border_start_scale = 4.0f;    // 400% of normal width, right after an edit
+        static constexpr float border_end_scale = 2.5f;      // 250% of normal width, right before commit
+    };
+}