teek-ui 0.1.0

data/test/test_overlay.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../../test/tk_test_helper'
+
+# ui.overlay floats a single widget on top of the enclosing ui.canvas at a
+# fixed corner/edge/center anchor, via Tk's `place` geometry manager - the
+# one legitimate "absolute position" case (a status readout or button bar
+# layered over canvas content), not a general-purpose layout mode.
+class TestOverlay < Minitest::Test
+  include TeekTestHelper
+
+  def test_overlay_places_the_widget_at_the_right_anchor
+    assert_tk_app("overlay should place its widget in the canvas at the anchor's relx/rely/anchor") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Overlay Test') do |ui|
+        ui.canvas(:board, width: 300, height: 200) do |cv|
+          cv.overlay(at: :bottom_right) { ui.label(:status, text: 'Ready') }
+        end
+      end
+      session.run_async
+      session.app.update
+
+      info = session.app.tcl_eval("place info #{session[:status].path}")
+      assert_match(/-in #{Regexp.escape(session[:board].path)}(?:\s|$)/, info)
+      assert_match(/-relx 1(?:\s|$)/, info)
+      assert_match(/-rely 1(?:\s|$)/, info)
+      assert_match(/-anchor se(?:\s|$)/, info)
+
+      session.app.destroy
+    end
+  end
+
+  def test_two_overlays_position_independently
+    assert_tk_app("two overlays on the same canvas should each land at their own anchor") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Overlay Test') do |ui|
+        ui.canvas(:board, width: 300, height: 200) do |cv|
+          cv.overlay(at: :top_left) { ui.label(:status, text: 'Ready') }
+          cv.overlay(at: :top_right) { ui.row(:controls) { ui.button(:pause, text: 'Pause') } }
+        end
+      end
+      session.run_async
+      session.app.update
+
+      status_info = session.app.tcl_eval("place info #{session[:status].path}")
+      controls_info = session.app.tcl_eval("place info #{session[:controls].path}")
+
+      assert_match(/-relx 0(?:\s|$)/, status_info)
+      assert_match(/-rely 0(?:\s|$)/, status_info)
+      assert_match(/-anchor nw(?:\s|$)/, status_info)
+
+      assert_match(/-relx 1(?:\s|$)/, controls_info)
+      assert_match(/-rely 0(?:\s|$)/, controls_info)
+      assert_match(/-anchor ne(?:\s|$)/, controls_info)
+
+      session.app.destroy
+    end
+  end
+
+  def test_overlay_tracks_a_canvas_resize
+    assert_tk_app("an overlay's real on-screen position should scale with the canvas, not stay fixed") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Overlay Test') do |ui|
+        ui.canvas(:board, width: 200, height: 200) do |cv|
+          cv.overlay(at: :bottom_right) { ui.label(:status, text: 'Ready') }
+        end
+      end
+      session.run_async
+      session.app.update
+
+      before_x = session.app.tcl_eval("winfo x #{session[:status].path}").to_i
+      before_y = session.app.tcl_eval("winfo y #{session[:status].path}").to_i
+
+      session.app.tcl_eval("#{session[:board].path} configure -width 500 -height 500")
+      session.app.update
+
+      after_x = session.app.tcl_eval("winfo x #{session[:status].path}").to_i
+      after_y = session.app.tcl_eval("winfo y #{session[:status].path}").to_i
+
+      assert_operator after_x, :>, before_x, "the overlay should have followed the canvas's new bottom-right corner"
+      assert_operator after_y, :>, before_y, "the overlay should have followed the canvas's new bottom-right corner"
+
+      session.app.destroy
+    end
+  end
+
+  def test_overlay_outside_a_canvas_raises
+    assert_tk_app("overlay declared outside ui.canvas should raise immediately, not silently do nothing") do
+      require 'teek/ui'
+
+      error = assert_raises(ArgumentError) do
+        Teek::UI.app(title: 'Overlay Test') { |ui| ui.overlay(at: :top_left) { ui.label(text: 'oops') } }
+      end
+      assert_match(/ui\.canvas/i, error.message)
+    end
+  end
+
+  def test_overlay_with_an_invalid_anchor_raises
+    assert_tk_app("overlay given an unrecognized at: should raise, not silently no-op") do
+      require 'teek/ui'
+
+      error = assert_raises(ArgumentError) do
+        Teek::UI.app(title: 'Overlay Test') do |ui|
+          ui.canvas(:board, width: 200, height: 200) { |cv| cv.overlay(at: :middle) { ui.label(text: 'oops') } }
+        end
+      end
+      assert_match(/at:/, error.message)
+    end
+  end
+
+  def test_overlay_requiring_exactly_one_widget_raises_on_zero_or_many
+    assert_tk_app("overlay's block must build exactly one widget") do
+      require 'teek/ui'
+
+      empty_error = assert_raises(ArgumentError) do
+        Teek::UI.app(title: 'Overlay Test') do |ui|
+          ui.canvas(:board, width: 200, height: 200) { |cv| cv.overlay(at: :top_left) { } }
+        end
+      end
+      assert_match(/exactly one/i, empty_error.message)
+
+      many_error = assert_raises(ArgumentError) do
+        Teek::UI.app(title: 'Overlay Test') do |ui|
+          ui.canvas(:board, width: 200, height: 200) do |cv|
+            cv.overlay(at: :top_left) do
+              ui.label(text: 'one')
+              ui.label(text: 'two')
+            end
+          end
+        end
+      end
+      assert_match(/exactly one/i, many_error.message)
+    end
+  end
+end

data/test/test_raw.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../../test/tk_test_helper'
+
+class TestRaw < Minitest::Test
+  include TeekTestHelper
+
+  def test_raw_runs_at_realize_with_a_working_live_app
+    assert_tk_app("ui.raw's block should run at realize, with a real, usable app") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Raw Test') do |ui|
+        ui.raw { |app| app.command('ttk::label', '.raw_label', text: 'from raw') }
+      end
+      session.run_async
+      session.app.update
+
+      assert session.app.winfo.exists?('.raw_label')
+      assert_equal 'from raw', session.app.command('.raw_label', :cget, '-text')
+
+      session.app.destroy
+    end
+  end
+
+  def test_raw_does_not_run_before_realize
+    assert_tk_app("ui.raw's block should not fire during build, only at realize") do
+      require 'teek/ui'
+
+      executed = false
+      session = Teek::UI.app(title: 'Raw Test') { |ui| ui.raw { |_app| executed = true } }
+
+      refute executed, "raw block ran during build, before any interpreter existed"
+
+      session.realize
+      assert executed, "raw block did not run at realize"
+
+      session.app.destroy
+    end
+  end
+
+  def test_raw_op_resolves_a_forward_referenced_sibling_by_name
+    assert_tk_app("a raw op declared before a sibling it references should still resolve its realized path") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Raw Test') do |ui|
+        ui.raw { |app| app.command(ui[:later].path, :configure, text: 'Changed by raw') }
+        ui.button(:later, text: 'Original')
+      end
+      session.run_async
+      session.app.update
+
+      assert_equal 'Changed by raw', session.app.command(session[:later].path, :cget, '-text')
+
+      session.app.destroy
+    end
+  end
+end

data/test/test_reactive_vars.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../../test/tk_test_helper'
+
+class TestReactiveVars < Minitest::Test
+  include TeekTestHelper
+
+  def test_slider_and_label_stay_in_sync_bidirectionally
+    assert_tk_app("a var bound to a slider and a label should keep both in sync") do
+      require 'teek/ui'
+
+      speed = nil
+      session = Teek::UI.app(title: 'Reactive Vars Test') do |ui|
+        speed = ui.var(5)
+        ui.slider(:speed_slider, from: 1, to: 10, bind: speed)
+        ui.label(:speed_label, bind: speed)
+      end
+      session.run_async
+      session.app.update
+
+      assert_equal 5, speed.value
+
+      slider_path = session[:speed_slider].path
+      label_path = session[:speed_label].path
+
+      # slider -> var -> label
+      # ttk::scale always stores/formats its bound variable as a float
+      # (e.g. "7.0"), even for a whole-number -from/-to range - compare
+      # numerically rather than assuming a particular string format.
+      session.app.command(slider_path, :set, 7)
+      session.app.update
+      assert_equal 7, speed.value
+      assert_equal 7.0, session.app.command(label_path, :cget, '-text').to_f
+
+      # var -> slider and label
+      speed.value = 3
+      session.app.update
+      assert_equal 3.0, session.app.command(slider_path, :get).to_f
+      assert_equal 3.0, session.app.command(label_path, :cget, '-text').to_f
+
+      session.app.destroy
+    end
+  end
+
+  def test_text_box_is_two_way
+    assert_tk_app("a var bound to a text_box should sync in both directions") do
+      require 'teek/ui'
+
+      name = nil
+      session = Teek::UI.app(title: 'Reactive Vars Test') { |ui| name = ui.var(''); ui.text_box(:name_box, bind: name) }
+      session.run_async
+      session.app.update
+
+      # var -> text_box
+      name.value = 'hello'
+      session.app.update
+      assert_equal 'hello', session.app.command(session[:name_box].path, :get)
+
+      # text_box -> var
+      box_path = session[:name_box].path
+      session.app.command(box_path, :delete, 0, :end)
+      session.app.command(box_path, :insert, 0, 'typed')
+      session.app.update
+      assert_equal 'typed', name.value
+
+      session.app.destroy
+    end
+  end
+
+  def test_on_change_fires_with_the_coerced_value_regardless_of_which_widget_changed_it
+    assert_tk_app("on_change should fire with a coerced Integer, triggered by the bound widget") do
+      require 'teek/ui'
+
+      speed = nil
+      changes = []
+      session = Teek::UI.app(title: 'Reactive Vars Test') do |ui|
+        speed = ui.var(5)
+        speed.on_change { |v| changes << v }
+        ui.slider(:speed_slider, from: 1, to: 10, bind: speed)
+      end
+      session.run_async
+      session.app.update
+
+      session.app.command(session[:speed_slider].path, :set, 9)
+      session.app.update
+
+      assert_includes changes, 9
+      assert_kind_of Integer, changes.last
+
+      session.app.destroy
+    end
+  end
+
+  def test_boolean_var_coerces_correctly_for_a_checkbox
+    assert_tk_app("a Boolean var bound to a checkbox should use Tk's 1/0 convention and coerce back to true/false") do
+      require 'teek/ui'
+
+      enabled = nil
+      session = Teek::UI.app(title: 'Reactive Vars Test') do |ui|
+        enabled = ui.var(true)
+        ui.checkbox(:enabled_box, bind: enabled)
+      end
+      session.run_async
+      session.app.update
+
+      assert_equal true, enabled.value
+      assert_equal '1', session.app.get_variable(enabled.name)
+
+      enabled.value = false
+      session.app.update
+      assert_equal false, enabled.value
+      assert_equal '0', session.app.get_variable(enabled.name)
+
+      session.app.destroy
+    end
+  end
+end

data/test/test_realizer.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../../test/tk_test_helper'
+
+class TestRealizer < Minitest::Test
+  include TeekTestHelper
+
+  def test_realize_creates_real_mapped_widgets_with_hierarchical_paths
+    assert_tk_app("realizing a nested tree should create real, mapped widgets at hierarchical paths") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Realizer Test') do |ui|
+        ui.panel(:controls) do |p|
+          p.button(:go, text: 'Go')
+        end
+      end
+      session.run_async
+      session.app.update
+
+      go_handle = session[:go]
+      assert_equal '.controls.go', go_handle.path
+      assert session.app.winfo.exists?(go_handle.path)
+      assert session.app.winfo.ismapped?(go_handle.path), "realized widgets should be packed/visible, not just created"
+
+      session.app.destroy
+    end
+  end
+
+  def test_unnamed_nodes_get_a_valid_auto_generated_path_segment
+    assert_tk_app("an unnamed node should still realize to a real, addressable Tk path") do
+      require 'teek/ui'
+
+      handle = nil
+      session = Teek::UI.app(title: 'Realizer Test') { |ui| handle = ui.label(text: 'Hi') }
+      session.run_async
+      session.app.update
+
+      assert session.app.winfo.exists?(handle.path)
+      # unnamed nodes get their Document-assigned key (e.g. "#anon1") as
+      # their path segment - unique for the whole document, not a
+      # per-Realizer-instance counter, so it stays collision-free across
+      # separate realize_subtree calls too (see Session#add).
+      assert_match(/\A\.\S+\z/, handle.path)
+
+      session.app.destroy
+    end
+  end
+
+  def test_handle_configure_mutates_the_live_widget_post_realize
+    assert_tk_app("handle.configure after realize should mutate the real widget") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Realizer Test') { |ui| ui.label(:greeting, text: 'Hi') }
+      session.run_async
+      session.app.update
+
+      session[:greeting].configure(text: 'Bye')
+
+      assert_equal 'Bye', session.app.command(session[:greeting].path, :cget, '-text')
+
+      session.app.destroy
+    end
+  end
+
+  def test_forward_event_target_reference_resolves_and_fires
+    assert_tk_app("an event binding targeting a widget declared later should resolve once the whole tree is realized") do
+      require 'teek/ui'
+
+      fired = false
+      session = Teek::UI.app(title: 'Realizer Test') do |ui|
+        ui.button(:trigger, text: 'Trigger')
+        ui.label(:downstream, text: 'Target') # declared AFTER :trigger
+
+        # white-box: no event DSL yet (that's a separate bead), so attach the
+        # binding directly the way the future DSL will - a forward reference
+        # by name to a node the realizer hasn't created yet at build time.
+        ui.document.find(:trigger).events <<
+          Teek::UI::EventBinding.new(event: '<Button-1>', handler: -> { fired = true }, target: :downstream)
+      end
+      session.run_async
+      session.app.update
+
+      downstream_path = session[:downstream].path
+      session.app.tcl_eval("event generate #{downstream_path} <Button-1>")
+      session.app.update
+
+      assert fired, "the forward-referenced target's binding did not fire"
+
+      session.app.destroy
+    end
+  end
+
+  def test_event_target_inside_a_component_resolves_to_that_components_own_node_not_a_siblings
+    assert_tk_app("a binding target inside a component should resolve to THAT component's like-named node, never a sibling component's") do
+      require 'teek/ui'
+
+      a_fired = false
+      b_fired = false
+      comp_a_downstream = nil
+      session = Teek::UI.app(title: 'Realizer Test') do |ui|
+        # each component nested under its own panel, matching how
+        # test_component_realtk.rb mounts like-named siblings - two
+        # components' children only get distinct real Tk paths when they
+        # sit under different real parents.
+        ui.panel(:panel_a) do |p|
+          p.component { |c| c.button(:trigger, text: 'Trigger A'); comp_a_downstream = c.label(:downstream, text: 'Target A') }
+        end
+        ui.panel(:panel_b) do |p|
+          p.component { |c| c.button(:trigger, text: 'Trigger B'); c.label(:downstream, text: 'Target B') }
+        end
+
+        # white-box: target: isn't public DSL yet (see the plain forward-
+        # reference test above) - a component's own nodes aren't reachable
+        # by name from outside its scope, so walk the tree structurally
+        # (each panel has one component's 2 children as its own children,
+        # in build order) to attach each component's own binding. A
+        # binding's event listener attaches to the TARGET node's path (see
+        # the plain forward-reference test above), so generating the event
+        # on component A's own :downstream widget below only fires
+        # component A's binding if resolution correctly stayed within
+        # component A's scope.
+        comp_a_trigger_node, comp_a_downstream_node = ui.document.find(:panel_a).children
+        comp_b_trigger_node, comp_b_downstream_node = ui.document.find(:panel_b).children
+        comp_a_trigger_node.events <<
+          Teek::UI::EventBinding.new(event: '<Button-1>', handler: -> { a_fired = true }, target: :downstream)
+        comp_b_trigger_node.events <<
+          Teek::UI::EventBinding.new(event: '<Button-1>', handler: -> { b_fired = true }, target: :downstream)
+        raise "unexpected build shape" unless comp_a_downstream_node && comp_b_downstream_node
+      end
+      session.run_async
+      session.app.update
+
+      session.app.tcl_eval("event generate #{comp_a_downstream.path} <Button-1>")
+      session.app.update
+
+      assert a_fired, "component A's own trigger should have fired component A's own binding"
+      refute b_fired, "component A's trigger firing should never fire component B's binding"
+
+      session.app.destroy
+    end
+  end
+
+  def test_event_target_forward_reference_still_resolves_inside_a_component
+    assert_tk_app("a forward reference to a not-yet-built sibling should still resolve when both are inside the same component") do
+      require 'teek/ui'
+
+      fired = false
+      session = Teek::UI.app(title: 'Realizer Test') do |ui|
+        ui.component do |c|
+          c.button(:trigger, text: 'Trigger')
+          c.label(:downstream, text: 'Target') # declared AFTER :trigger, same component
+
+          trigger_node, = c.document.root.children
+          trigger_node.events <<
+            Teek::UI::EventBinding.new(event: '<Button-1>', handler: -> { fired = true }, target: :downstream)
+        end
+      end
+      session.run_async
+      session.app.update
+
+      _trigger_node, downstream_node = session.document.root.children
+      session.app.tcl_eval("event generate #{downstream_node.realized.path} <Button-1>")
+      session.app.update
+
+      assert fired, "the intra-component forward-referenced target's binding did not fire"
+
+      session.app.destroy
+    end
+  end
+
+  def test_realize_is_atomic_on_a_mid_realize_error
+    assert_tk_app("an error partway through realize should leave the root window unmapped and the session not realized") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Realizer Test') do |ui|
+        ui.label(:first, text: 'Ok')
+        ui.document.root.add_child(Teek::UI::Node.new(type: :not_a_real_widget_type, name: :bad))
+      end
+
+      assert_raises(StandardError) { session.realize }
+
+      assert_raises(Teek::UI::NotRealizedError) { session.app }
+    end
+  end
+
+  # Locks the invariant the validator's "mixed pack+grid" note relies on
+  # instead of checking directly: every container realizes into its own
+  # dedicated Tk master, and arrange_children picks exactly one geometry
+  # manager per master, so no master should ever end up with a mix of
+  # pack- and grid-managed children. Verified against the REAL, realized
+  # Tk widget tree (winfo children/winfo manager), not just teek-ui's own
+  # Document structure.
+  def test_no_realized_master_ever_receives_more_than_one_geometry_manager
+    assert_tk_app("every realized master frame should be managed by exactly one geometry manager - representative nested tree: column > grid > row > panel") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Realizer Test') do |ui|
+        ui.column(:outer, gap: 4) do |c|
+          c.grid(:g, gap: 2) do |g|
+            g.cell(row: 0, col: 0) { g.label(:l1, text: 'A') }
+            g.cell(row: 0, col: 1) do
+              g.row(:r, gap: 2) do |r|
+                r.button(:b1, text: 'B')
+                r.panel(:p) { |p| p.button(:b2, text: 'C') }
+              end
+            end
+          end
+          c.button(:outer_btn, text: 'D')
+        end
+      end
+      session.run_async
+      session.app.update
+
+      # walks the REAL, realized Tk widget tree (winfo children/winfo
+      # manager) rather than teek-ui's own Document structure - this is
+      # what would actually misbehave if the invariant ever broke, wherever
+      # the break came from. A local recursive lambda, not a helper method -
+      # assert_tk_app re-evaluates this block's own source text in a
+      # separate worker context, which has no access to methods defined on
+      # the surrounding Minitest::Test class.
+      check = lambda do |path|
+        children = session.app.split_list(session.app.tcl_eval("winfo children #{path}"))
+        managers = children.map { |child| session.app.tcl_eval("winfo manager #{child}") }.reject(&:empty?).uniq
+        assert_operator managers.length, :<=, 1,
+          "#{path} has children managed by more than one geometry manager: #{managers.inspect}"
+        children.each { |child| check.call(child) }
+      end
+      check.call('.')
+
+      session.app.destroy
+    end
+  end
+
+  # A genuinely mixed master turns out to be impossible to even construct
+  # via pack/grid themselves - Tk's own geometry-manager framework refuses
+  # a second manager type for a master once one is active, symmetrically
+  # (pack-then-grid and grid-then-pack both raise), with a clear, immediate
+  # Teek::TclError - NOT a silent hang, contrary to the original "Tk
+  # literally HANGS on this" framing this project started from. Confirmed
+  # empirically - place coexists safely with either, confirming overlay
+  # (not built yet, place-based) is a genuinely different, safe case. This
+  # is a second, independent safety net on top of the realizer's own
+  # one-manager-per-master construction invariant the test above locks -
+  # not a replacement for it.
+  def test_tk_itself_refuses_a_second_geometry_manager_on_one_master
+    assert_tk_app("Tk's own geometry-manager protection should refuse pack+grid mixing on one master with a clear error") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Realizer Test') { |ui| ui.panel(:guarded) }
+      session.run_async
+      session.app.update
+
+      session.app.command('ttk::button', '.guarded.a', text: 'A')
+      session.app.command('ttk::button', '.guarded.b', text: 'B')
+      session.app.command(:pack, '.guarded.a')
+
+      error = assert_raises(Teek::TclError) { session.app.command(:grid, '.guarded.b', row: 0, column: 0) }
+      assert_match(/geometry manager/i, error.message)
+
+      session.app.destroy
+    end
+  end
+end

data/test/test_scope.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+require 'teek/ui/scope'
+
+class TestScope < Minitest::Test
+  def test_top_level_is_top_level
+    assert Teek::UI::Scope::TOP_LEVEL.top_level?
+  end
+
+  def test_a_fresh_scope_is_not_top_level
+    refute Teek::UI::Scope.new.top_level?
+  end
+
+  def test_two_scopes_with_the_same_label_are_never_the_same_scope
+    a = Teek::UI::Scope.new(:widget)
+    b = Teek::UI::Scope.new(:widget)
+
+    refute a.equal?(b)
+  end
+
+  def test_parent_defaults_to_nil
+    assert_nil Teek::UI::Scope.new.parent
+  end
+
+  def test_parent_is_settable
+    parent = Teek::UI::Scope.new
+    child = Teek::UI::Scope.new(:child, parent: parent)
+
+    assert_same parent, child.parent
+  end
+
+  def test_label_is_readable
+    scope = Teek::UI::Scope.new(:sidebar)
+
+    assert_equal :sidebar, scope.label
+  end
+end