teek-ui 0.1.0

data/test/test_document.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+require 'teek/ui/document'
+require 'teek/ui/scope'
+require 'teek/ui/realized_node'
+
+class TestDocument < Minitest::Test
+  def test_root_is_an_empty_root_node
+    document = Teek::UI::Document.new
+
+    assert_kind_of Teek::UI::Node, document.root
+    assert_equal :root, document.root.type
+    assert_equal [], document.root.children
+  end
+
+  def test_create_builds_a_node_but_does_not_attach_it_to_any_parent
+    document = Teek::UI::Document.new
+
+    node = document.create(type: :button, opts: { text: 'Go' })
+
+    assert_equal :button, node.type
+    assert_equal({ text: 'Go' }, node.opts)
+    assert_equal [], document.root.children, "create should not attach the node anywhere - the caller decides the parent"
+  end
+
+  def test_named_node_is_findable_by_symbol_after_attaching
+    document = Teek::UI::Document.new
+    node = document.create(type: :button, name: :save)
+    document.root.add_child(node)
+
+    assert_same node, document.find(:save)
+    assert_same node, document[:save]
+  end
+
+  def test_create_gives_the_node_a_back_reference_to_the_document
+    document = Teek::UI::Document.new
+
+    node = document.create(type: :button, name: :save)
+
+    assert_same document, node.document
+  end
+
+  def test_unregister_removes_a_named_node_from_the_index
+    document = Teek::UI::Document.new
+    node = document.create(type: :button, name: :save)
+    document.root.add_child(node)
+
+    document.unregister(node)
+
+    assert_nil document.find(:save)
+  end
+
+  def test_unregister_frees_the_name_for_reuse
+    document = Teek::UI::Document.new
+    first = document.create(type: :button, name: :save)
+    document.root.add_child(first)
+    document.unregister(first)
+
+    second = document.create(type: :button, name: :save)
+
+    assert_same second, document.find(:save)
+  end
+
+  def test_unregister_on_an_unnamed_node_is_a_safe_no_op
+    document = Teek::UI::Document.new
+    node = document.create(type: :button)
+
+    document.unregister(node)
+  end
+
+  def test_unregister_only_affects_the_given_nodes_own_scope
+    document = Teek::UI::Document.new
+    scope = Teek::UI::Scope.new(:a)
+    top_level = document.create(type: :button, name: :save)
+    document.root.add_child(top_level)
+    scoped = document.create(type: :button, name: :save, scope: scope)
+
+    document.unregister(scoped)
+
+    assert_same top_level, document.find(:save)
+    assert_nil document.find(:save, scope: scope)
+  end
+
+  def test_find_returns_nil_for_an_unknown_name
+    document = Teek::UI::Document.new
+
+    assert_nil document.find(:nope)
+    assert_nil document[:nope]
+  end
+
+  def test_unnamed_nodes_get_a_distinct_auto_generated_key
+    document = Teek::UI::Document.new
+
+    a = document.create(type: :button)
+    b = document.create(type: :button)
+
+    refute_nil a.key
+    refute_nil b.key
+    refute_equal a.key, b.key
+  end
+
+  def test_named_node_key_is_the_name
+    document = Teek::UI::Document.new
+
+    node = document.create(type: :button, name: :save)
+
+    assert_equal 'save', node.key
+  end
+
+  def test_duplicate_explicit_name_is_detected
+    document = Teek::UI::Document.new
+    document.create(type: :button, name: :save)
+
+    error = assert_raises(ArgumentError) { document.create(type: :button, name: :save) }
+    assert_match(/save/, error.message)
+  end
+
+  def test_same_name_in_two_different_scopes_does_not_collide
+    document = Teek::UI::Document.new
+    scope_a = Teek::UI::Scope.new(:a)
+    scope_b = Teek::UI::Scope.new(:b)
+
+    a = document.create(type: :button, name: :save, scope: scope_a)
+    b = document.create(type: :button, name: :save, scope: scope_b)
+
+    refute_same a, b
+    assert_same a, document.find(:save, scope: scope_a)
+    assert_same b, document.find(:save, scope: scope_b)
+  end
+
+  def test_same_name_in_the_same_scope_still_collides
+    document = Teek::UI::Document.new
+    scope = Teek::UI::Scope.new(:a)
+    document.create(type: :button, name: :save, scope: scope)
+
+    error = assert_raises(ArgumentError) {
+      document.create(type: :button, name: :save, scope: scope)
+    }
+    assert_match(/save/, error.message)
+  end
+
+  def test_scoped_name_does_not_collide_with_the_same_name_at_top_level
+    document = Teek::UI::Document.new
+    scope = Teek::UI::Scope.new(:a)
+
+    top_level = document.create(type: :button, name: :save)
+    scoped = document.create(type: :button, name: :save, scope: scope)
+
+    refute_same top_level, scoped
+    assert_same top_level, document.find(:save)
+    assert_same scoped, document.find(:save, scope: scope)
+  end
+
+  def test_find_with_a_scope_does_not_find_a_top_level_node_of_the_same_name
+    document = Teek::UI::Document.new
+    document.create(type: :button, name: :save)
+
+    assert_nil document.find(:save, scope: Teek::UI::Scope.new(:a))
+  end
+
+  def test_find_without_a_scope_does_not_find_a_scoped_node_of_the_same_name
+    document = Teek::UI::Document.new
+    document.create(type: :button, name: :save, scope: Teek::UI::Scope.new(:a))
+
+    assert_nil document.find(:save)
+  end
+
+  def test_two_scopes_with_the_same_label_do_not_share_a_namespace
+    document = Teek::UI::Document.new
+    first = Teek::UI::Scope.new(:widget)
+    second = Teek::UI::Scope.new(:widget)
+
+    a = document.create(type: :button, name: :save, scope: first)
+    b = document.create(type: :button, name: :save, scope: second)
+
+    refute_same a, b
+    assert_same a, document.find(:save, scope: first)
+    assert_same b, document.find(:save, scope: second)
+  end
+
+  def test_each_node_traverses_the_whole_tree_from_root
+    document = Teek::UI::Document.new
+    a = document.create(type: :button, name: :a)
+    b = document.create(type: :column, name: :b)
+    c = document.create(type: :button, name: :c)
+    document.root.add_child(a)
+    document.root.add_child(b)
+    b.add_child(c)
+
+    visited = []
+    document.each_node { |n| visited << n }
+
+    assert_equal [document.root, a, b, c], visited
+  end
+
+  def test_claim_path_segment_returns_the_bare_segment_the_first_time
+    document = Teek::UI::Document.new
+
+    assert_equal 'save', document.claim_path_segment('.list', 'save')
+  end
+
+  def test_claim_path_segment_disambiguates_a_repeat_under_the_same_parent
+    document = Teek::UI::Document.new
+
+    document.claim_path_segment('.list', 'save')
+
+    assert_equal 'save#2', document.claim_path_segment('.list', 'save')
+    assert_equal 'save#3', document.claim_path_segment('.list', 'save')
+  end
+
+  def test_claim_path_segment_tracks_independently_per_parent_path
+    document = Teek::UI::Document.new
+
+    document.claim_path_segment('.sidebar', 'save')
+
+    assert_equal 'save', document.claim_path_segment('.main', 'save'),
+      "the same segment under a DIFFERENT parent should never need disambiguating"
+  end
+
+  def test_find_by_path_returns_the_node_whose_realized_path_matches
+    document = Teek::UI::Document.new
+    node = document.create(type: :button, name: :save)
+    document.root.add_child(node)
+    node.realized = Teek::UI::RealizedNode.new(app: nil, path: '.win.save')
+
+    assert_same node, document.find_by_path('.win.save')
+  end
+
+  def test_find_by_path_returns_nil_for_an_unrealized_node
+    document = Teek::UI::Document.new
+    node = document.create(type: :button, name: :save)
+    document.root.add_child(node)
+
+    assert_nil document.find_by_path('.win.save')
+  end
+
+  def test_find_by_path_returns_nil_for_an_unknown_path
+    document = Teek::UI::Document.new
+    node = document.create(type: :button, name: :save)
+    document.root.add_child(node)
+    node.realized = Teek::UI::RealizedNode.new(app: nil, path: '.win.save')
+
+    assert_nil document.find_by_path('.nope')
+  end
+
+  def test_find_by_path_distinguishes_a_scrollbar_wrapped_nodes_path_from_its_arrange_path
+    document = Teek::UI::Document.new
+    node = document.create(type: :list, name: :items)
+    document.root.add_child(node)
+    node.realized = Teek::UI::RealizedNode.new(app: nil, path: '.wrap.items', arrange_path: '.wrap')
+
+    assert_same node, document.find_by_path('.wrap.items'), "path is the real widget - what a Handle acts on"
+    assert_nil document.find_by_path('.wrap'), "arrange_path is only where the parent's layout places it, not this node's own address"
+  end
+
+  def test_claim_path_segment_persists_across_separate_calls_not_just_one_realizer_instance
+    document = Teek::UI::Document.new
+
+    document.claim_path_segment('.list', 'save')
+    # simulates two SEPARATE Realizer instances (e.g. the initial realize,
+    # then a later lazily-realized screen sharing the same internal
+    # component name) both claiming under the same real parent - the
+    # whole reason this lives on Document rather than Realizer itself.
+    assert_equal 'save#2', document.claim_path_segment('.list', 'save')
+  end
+
+  def test_add_child_notifies_append_subscribers
+    document = Teek::UI::Document.new
+    parent = document.create(type: :column, name: :ctrl)
+    child = document.create(type: :button)
+    seen = []
+    document.subscribe(:append) { |p, c| seen << [p, c] }
+
+    parent.add_child(child)
+
+    assert_equal [[parent, child]], seen
+  end
+
+  def test_add_child_is_silent_with_no_subscribers
+    document = Teek::UI::Document.new
+    parent = document.create(type: :column)
+    child = document.create(type: :button)
+
+    parent.add_child(child)
+  end
+
+  def test_notify_reaches_every_subscriber_of_that_event_in_order
+    document = Teek::UI::Document.new
+    seen = []
+    document.subscribe(:push) { |*args| seen << [:first, args] }
+    document.subscribe(:push) { |*args| seen << [:second, args] }
+
+    document.notify(:push, :some_node, 'column')
+
+    assert_equal [[:first, [:some_node, 'column']], [:second, [:some_node, 'column']]], seen
+  end
+
+  def test_notify_only_reaches_subscribers_of_that_specific_event
+    document = Teek::UI::Document.new
+    push_seen = []
+    document.subscribe(:push) { |*args| push_seen << args }
+
+    document.notify(:pop, :some_node, 'column')
+
+    assert_equal [], push_seen
+  end
+
+  def test_a_raw_node_new_with_no_document_never_calls_notify
+    parent = Teek::UI::Node.new(type: :column)
+    child = Teek::UI::Node.new(type: :button)
+
+    parent.add_child(child)
+
+    assert_equal [child], parent.children
+  end
+end

data/test/test_event_bus.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+require 'teek/ui/event_bus'
+require 'teek/ui/session'
+
+# In-process publish/subscribe for decoupled app events - not Tk events,
+# complementary to on_click/on_key (see Handle). Headless: no Tk/interpreter
+# involved at all, pure Ruby object messaging.
+class TestEventBus < Minitest::Test
+  def test_on_and_emit
+    bus = Teek::UI::EventBus.new
+    received = nil
+
+    bus.on(:ping) { |val| received = val }
+    bus.emit(:ping, 42)
+
+    assert_equal 42, received
+  end
+
+  def test_emit_with_no_subscribers_is_a_no_op
+    bus = Teek::UI::EventBus.new
+
+    bus.emit(:ghost, 1, 2, 3) # should not raise
+  end
+
+  def test_multiple_subscribers_all_fire_in_subscription_order
+    bus = Teek::UI::EventBus.new
+    results = []
+
+    bus.on(:tick) { |v| results << "a:#{v}" }
+    bus.on(:tick) { |v| results << "b:#{v}" }
+    bus.emit(:tick, 7)
+
+    assert_equal ['a:7', 'b:7'], results
+  end
+
+  def test_different_events_are_independent
+    bus = Teek::UI::EventBus.new
+    a = nil
+    b = nil
+
+    bus.on(:foo) { |v| a = v }
+    bus.on(:bar) { |v| b = v }
+    bus.emit(:foo, 1)
+
+    assert_equal 1, a
+    assert_nil b
+  end
+
+  def test_emit_forwards_multiple_positional_args
+    bus = Teek::UI::EventBus.new
+    received = nil
+
+    bus.on(:multi) { |x, y| received = [x, y] }
+    bus.emit(:multi, :a, :b)
+
+    assert_equal [:a, :b], received
+  end
+
+  def test_emit_forwards_keyword_args
+    bus = Teek::UI::EventBus.new
+    received = nil
+
+    bus.on(:kw) { |name:, val:| received = { name: name, val: val } }
+    bus.emit(:kw, name: 'scale', val: 3)
+
+    assert_equal({ name: 'scale', val: 3 }, received)
+  end
+
+  def test_off_removes_a_specific_subscriber
+    bus = Teek::UI::EventBus.new
+    received = []
+
+    block = bus.on(:evt) { |v| received << v }
+    bus.emit(:evt, 1)
+    bus.off(:evt, block)
+    bus.emit(:evt, 2)
+
+    assert_equal [1], received
+  end
+
+  def test_off_only_removes_the_given_subscriber_not_others_on_the_same_event
+    bus = Teek::UI::EventBus.new
+    received = []
+
+    keep = bus.on(:evt) { |v| received << "keep:#{v}" }
+    drop = bus.on(:evt) { |v| received << "drop:#{v}" }
+    bus.off(:evt, drop)
+    bus.emit(:evt, 1)
+
+    assert_equal ['keep:1'], received
+    refute_nil keep
+  end
+
+  def test_on_returns_the_block_for_a_later_off
+    bus = Teek::UI::EventBus.new
+
+    block = bus.on(:x) { }
+
+    assert_instance_of Proc, block
+  end
+
+  def test_two_independent_buses_do_not_see_each_others_events
+    bus_a = Teek::UI::EventBus.new
+    bus_b = Teek::UI::EventBus.new
+    received_a = nil
+    received_b = nil
+
+    bus_a.on(:shared_name) { |v| received_a = v }
+    bus_b.on(:shared_name) { |v| received_b = v }
+    bus_a.emit(:shared_name, 'from a')
+
+    assert_equal 'from a', received_a
+    assert_nil received_b, "bus_b should never see bus_a's emit"
+  end
+end
+
+# Session#on/#emit/#off delegate to one EventBus per session - app-scoped,
+# not a global singleton, so two Teek::UI.app instances in the same
+# process never see each other's events. Headless: works before realize,
+# no Tk/interpreter needed at all.
+class TestSessionEventBus < Minitest::Test
+  def build_session
+    Teek::UI::Session.new(title: 'Event Bus Test')
+  end
+
+  def test_on_and_emit_work_before_realize
+    session = build_session
+    received = nil
+
+    session.on(:item_selected) { |id| received = id }
+    session.emit(:item_selected, 42)
+
+    assert_equal 42, received
+  end
+
+  def test_off_removes_a_specific_subscriber
+    session = build_session
+    received = []
+
+    block = session.on(:evt) { |v| received << v }
+    session.emit(:evt, 1)
+    session.off(:evt, block)
+    session.emit(:evt, 2)
+
+    assert_equal [1], received
+  end
+
+  def test_two_independent_sessions_do_not_see_each_others_events
+    session_a = build_session
+    session_b = build_session
+    received_a = nil
+    received_b = nil
+
+    session_a.on(:theme_changed) { |v| received_a = v }
+    session_b.on(:theme_changed) { |v| received_b = v }
+    session_a.emit(:theme_changed, 'dark')
+
+    assert_equal 'dark', received_a
+    assert_nil received_b, "session_b should never see session_a's emit"
+  end
+end

data/test/test_events.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../../test/tk_test_helper'
+
+class TestEvents < Minitest::Test
+  include TeekTestHelper
+
+  def test_on_click_fires_on_a_real_button_event
+    assert_tk_app("on_click should fire when Button-1 is generated on the widget") do
+      require 'teek/ui'
+
+      clicked = false
+      session = Teek::UI.app(title: 'Events Test') { |ui| ui.button(:go, text: 'Go') }
+      session.run_async
+      session.app.update
+      session[:go].on_click { clicked = true }
+
+      session.app.tcl_eval("event generate #{session[:go].path} <Button-1>")
+      session.app.update
+
+      assert clicked, "on_click did not fire"
+
+      session.app.destroy
+    end
+  end
+
+  def test_on_right_click_fires_on_the_linux_windows_right_click_event
+    assert_tk_app("on_right_click should fire on Button-3 (Linux/Windows right-click)") do
+      require 'teek/ui'
+
+      clicked = false
+      session = Teek::UI.app(title: 'Events Test') { |ui| ui.button(:go, text: 'Go') }
+      session.run_async
+      session.app.update
+      session[:go].on_right_click { clicked = true }
+
+      session.app.tcl_eval("event generate #{session[:go].path} <Button-3>")
+      session.app.update
+
+      assert clicked, "on_right_click did not fire on Button-3"
+
+      session.app.destroy
+    end
+  end
+
+  def test_on_drag_delivers_typed_integer_coordinates
+    assert_tk_app("on_drag should deliver Integer x/y, not raw Tcl strings") do
+      require 'teek/ui'
+
+      received = nil
+      session = Teek::UI.app(title: 'Events Test') { |ui| ui.panel(:area, width: 200, height: 200) }
+      session.run_async
+      session.app.update
+      session[:area].on_drag { |x, y| received = [x, y] }
+
+      session.app.tcl_eval("event generate #{session[:area].path} <B1-Motion> -x 40 -y 55")
+      session.app.update
+
+      assert_equal [40, 55], received
+      assert_kind_of Integer, received[0]
+      assert_kind_of Integer, received[1]
+
+      session.app.destroy
+    end
+  end
+
+  def test_on_drag_converts_coordinates_when_bound_to_a_canvas
+    assert_tk_app("on_drag should convert raw window coords through canvasx/canvasy when bound to a canvas") do
+      require 'teek/ui'
+
+      received = nil
+      session = Teek::UI.app(title: 'Events Test') { |ui| ui.canvas(:board, width: 200, height: 200) }
+      session.run_async
+      session.app.update
+
+      board_path = session[:board].path
+      # scroll the canvas so canvasx/canvasy meaningfully differ from raw %x/%y -
+      # otherwise a bug that skips conversion entirely could still pass by luck.
+      session.app.tcl_eval("#{board_path} configure -scrollregion {0 0 1000 1000}")
+      session.app.tcl_eval("#{board_path} xview moveto 0.5")
+      session.app.update
+
+      session[:board].on_drag { |x, y| received = [x, y] }
+      session.app.tcl_eval("event generate #{board_path} <B1-Motion> -x 50 -y 60")
+      session.app.update
+
+      expected_x = session.app.command(board_path, :canvasx, 50).to_f.round
+      expected_y = session.app.command(board_path, :canvasy, 60).to_f.round
+
+      refute_nil received
+      assert_equal [expected_x, expected_y], received
+      refute_equal [50, 60], received, "the canvas is scrolled, so conversion should actually change the coordinates"
+
+      session.app.destroy
+    end
+  end
+
+  def test_on_key_resolves_a_friendly_symbol
+    assert_tk_app("on_key(:enter) should fire on a real Return keypress") do
+      require 'teek/ui'
+
+      fired = false
+      session = Teek::UI.app(title: 'Events Test') { |ui| ui.text_box(:query) }
+      session.run_async
+      session.app.update
+      session[:query].on_key(:enter) { fired = true }
+
+      path = session[:query].path
+      session.app.tcl_eval("focus -force #{path}")
+      session.app.update
+      session.app.tcl_eval("event generate #{path} <Return>")
+      session.app.update
+
+      assert fired, "on_key(:enter) did not fire"
+
+      session.app.destroy
+    end
+  end
+
+  def test_on_key_resolves_a_ctrl_modifier_string
+    assert_tk_app("on_key('Ctrl-s') should fire on a real Control-s keypress") do
+      require 'teek/ui'
+
+      fired = false
+      session = Teek::UI.app(title: 'Events Test') { |ui| ui.text_box(:query) }
+      session.run_async
+      session.app.update
+      session[:query].on_key('Ctrl-s') { fired = true }
+
+      path = session[:query].path
+      session.app.tcl_eval("focus -force #{path}")
+      session.app.update
+      session.app.tcl_eval("event generate #{path} <Control-s>")
+      session.app.update
+
+      assert fired, "on_key('Ctrl-s') did not fire"
+
+      session.app.destroy
+    end
+  end
+
+  def test_on_key_shift_tab_fires_via_the_iso_left_tab_gotcha
+    assert_tk_app("on_key('Shift-Tab') should fire even though X11 delivers it as ISO_Left_Tab, not Shift-Tab") do
+      require 'teek/ui'
+
+      fired = false
+      session = Teek::UI.app(title: 'Events Test') { |ui| ui.text_box(:query) }
+      session.run_async
+      session.app.update
+      session[:query].on_key('Shift-Tab') { fired = true }
+
+      path = session[:query].path
+      session.app.tcl_eval("focus -force #{path}")
+      session.app.update
+      session.app.tcl_eval("event generate #{path} <ISO_Left_Tab>")
+      session.app.update
+
+      assert fired, "on_key('Shift-Tab') did not fire for the X11 ISO_Left_Tab keysym"
+
+      session.app.destroy
+    end
+  end
+end

data/test/test_fake_app_contract.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+require 'teek'
+
+# support/fake_app.rb's FakeApp/FakeWindow stand in for Teek::App/
+# Teek::Window in headless tests - Realizer/Handle only ever call a
+# handful of methods on whichever app object they're given, so the fakes
+# implement just those, not the real classes' full surface. What they DO
+# implement needs to stay call-compatible with the real thing, or a
+# headless test could keep passing against a contract production code no
+# longer honors. RSpec has verifying doubles (instance_double) for
+# exactly this; Minitest doesn't, so this hand-rolls the same idea as an
+# ordinary failing test instead of a load-time check that would just
+# blow up the whole suite with a raw exception.
+class TestFakeAppContract < Minitest::Test
+  FAKE_APP_METHODS = %i[command bind on_close popup_menu window].freeze
+  FAKE_WINDOW_METHODS = %i[modal grab_release].freeze
+
+  def test_fake_app_methods_are_signature_compatible_with_teek_app
+    FAKE_APP_METHODS.each do |name|
+      assert_signature_compatible(FakeApp.instance_method(name), Teek::App.instance_method(name), name)
+    end
+  end
+
+  def test_fake_window_methods_are_signature_compatible_with_teek_window
+    FAKE_WINDOW_METHODS.each do |name|
+      assert_signature_compatible(FakeWindow.instance_method(name), Teek::Window.instance_method(name), name)
+    end
+  end
+
+  private
+
+  # Keyword names must match exactly (a renamed/added/removed kwarg is
+  # the drift most likely to silently break a fake) - required vs
+  # optional isn't distinguished, since the fake defaulting a kwarg the
+  # real method requires is a harmless, common simplification for a stub.
+  # Positional/rest SHAPE (ignoring req vs opt, same reasoning) must also
+  # line up, since a dropped or added *args changes what call sites the
+  # fake can stand in for. +&block+ presence is deliberately NOT compared
+  # - a real method can accept a block via bare +yield+/+block_given?+
+  # with no +&block+ param at all (see Teek::Window#modal), which
+  # +Method#parameters+ has no way to see - only a fake DECLARING a block
+  # param when the real method can't take one at all would be a genuine
+  # mismatch, and that's not a failure mode worth the false positives
+  # this check would otherwise raise on every yield-based real method.
+  def assert_signature_compatible(fake_method, real_method, name)
+    assert_equal keyword_names(real_method), keyword_names(fake_method),
+      "FakeApp/FakeWindow##{name}'s keyword arguments have drifted from the real Teek method's"
+
+    assert_equal positional_shape(real_method), positional_shape(fake_method),
+      "FakeApp/FakeWindow##{name}'s positional/rest shape has drifted from the real Teek method's"
+  end
+
+  def keyword_names(method)
+    method.parameters.select { |kind, _| %i[key keyreq].include?(kind) }.map { |_, param_name| param_name }.sort
+  end
+
+  def positional_shape(method)
+    method.parameters.reject { |kind, _| %i[key keyreq keyrest block].include?(kind) }.map { |kind, _| kind }
+  end
+end