teek-ui 0.1.0

data/test/test_incremental_realize.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../../test/tk_test_helper'
+
+class TestIncrementalRealize < Minitest::Test
+  include TeekTestHelper
+
+  def test_add_creates_and_shows_new_widgets_in_a_running_app
+    assert_tk_app("ui.add should create and show new widgets in an already-running app") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Incremental Realize Test') { |ui| ui.column(:list) }
+      session.run_async
+      session.app.update
+
+      session.add(:list) { |a| a.button(:item1, text: 'Item 1') }
+      session.app.update
+
+      assert session.app.winfo.exists?(session[:item1].path)
+      assert session.app.winfo.ismapped?(session[:item1].path)
+
+      session.app.destroy
+    end
+  end
+
+  def test_add_creates_multiple_new_siblings_declared_in_one_block
+    assert_tk_app("adding several new widgets inside ONE session.add block should not crash arrange_children on a not-yet-created sibling, and should arrange all of them correctly") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Incremental Realize Test') { |ui| ui.column(:list, gap: 10) }
+      session.run_async
+      session.app.update
+
+      handles = []
+      session.add(:list) { |a| 3.times { |i| handles << a.button(text: "Item #{i}") } }
+      session.app.update
+
+      children = session.document.find(:list).children
+      assert_equal 3, children.length
+      children.each { |child| assert session.app.winfo.exists?(child.realized.path) }
+
+      # a not-yet-created batch-mate shouldn't just avoid crashing - it
+      # should end up correctly positioned too, exactly like an ordinary
+      # sequence of separate session.add calls would (see
+      # test_add_respects_gap_relative_to_pre_existing_siblings above).
+      handles.each_cons(2) do |above, below|
+        above_bottom = session.app.winfo.rooty(above.path) + session.app.winfo.height(above.path)
+        below_top = session.app.winfo.rooty(below.path)
+        assert_equal 10, below_top - above_bottom
+      end
+
+      session.app.destroy
+    end
+  end
+
+  def test_add_respects_gap_relative_to_pre_existing_siblings
+    assert_tk_app("a widget added to a flow container should respect gap: relative to widgets already there") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Incremental Realize Test') do |ui|
+        ui.column(:list, gap: 20) { |c| c.button(:first, text: 'First') }
+      end
+      session.run_async
+      session.app.update
+
+      session.add(:list) { |a| a.button(:second, text: 'Second') }
+      session.app.update
+
+      first_bottom = session.app.winfo.rooty(session[:first].path) + session.app.winfo.height(session[:first].path)
+      second_top = session.app.winfo.rooty(session[:second].path)
+
+      assert_equal 20, second_top - first_bottom
+
+      session.app.destroy
+    end
+  end
+
+  def test_events_wired_inside_add_fire_correctly
+    assert_tk_app("on_click wired inside an add block should fire, using the same queue-then-wire-at-link path the initial build uses") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Incremental Realize Test') { |ui| ui.column(:list) }
+      session.run_async
+      session.app.update
+
+      clicked = false
+      session.add(:list) { |a| a.button(:item1, text: 'Item 1').on_click { clicked = true } }
+      session.app.update
+
+      session.app.tcl_eval("event generate #{session[:item1].path} <Button-1>")
+      session.app.update
+
+      assert clicked, "on_click wired inside ui.add did not fire"
+
+      session.app.destroy
+    end
+  end
+
+  def test_destroying_an_added_widget_reclaims_its_callback
+    assert_tk_app("destroying an incrementally-added widget should release its callback via teek's existing <Destroy> machinery") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Incremental Realize Test') { |ui| ui.column(:list) }
+      session.run_async
+      session.app.update
+      baseline = session.app.interp.callback_ids.length
+
+      session.add(:list) { |a| a.button(:item1, text: 'Item 1').on_click { } }
+      session.app.update
+      assert_equal baseline + 1, session.app.interp.callback_ids.length, "adding should register one callback"
+
+      session.app.destroy(session[:item1].path)
+      session.app.update
+
+      assert_equal baseline, session.app.interp.callback_ids.length, "destroying the added widget should release its callback"
+
+      session.app.destroy
+    end
+  end
+
+  def test_a_var_declared_inside_add_is_realized_and_works
+    assert_tk_app("ui.var declared inside an add block should get its backing Tcl variable, not stay forever unrealized") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Incremental Realize Test') { |ui| ui.column(:list) }
+      session.run_async
+      session.app.update
+
+      count = nil
+      session.add(:list) do |a|
+        count = a.var(5)
+        a.label(:count_label, bind: count)
+      end
+      session.app.update
+
+      assert_equal 5, count.value
+      assert_equal '5', session.app.command(session[:count_label].path, :cget, '-text')
+
+      count.value = 9
+      session.app.update
+      assert_equal '9', session.app.command(session[:count_label].path, :cget, '-text')
+
+      session.app.destroy
+    end
+  end
+
+  def test_an_image_declared_inside_add_is_realized_and_displays
+    assert_tk_app("ui.image declared inside an add block should actually load, not raise 'image does not exist' - the ChildWindow fresh-mount-per-open pattern depends on this") do
+      require 'teek/ui'
+      require 'tmpdir'
+
+      Dir.mktmpdir do |dir|
+        path = File.join(dir, 'test.png')
+        seed = Teek::Photo.new(app, width: 4, height: 4)
+        seed.put_block(([0, 0, 0, 255].pack('CCCC')) * 16, 4, 4)
+        app.tcl_eval("#{seed.name} write {#{path}} -format png")
+        seed.delete
+
+        session = Teek::UI.app(title: 'Incremental Realize Test') { |ui| ui.column(:list) }
+        session.run_async
+        session.app.update
+
+        icon = nil
+        session.add(:list) do |a|
+          icon = a.image(path)
+          a.label(:pic, image: icon)
+        end
+        session.app.update
+
+        assert_equal icon.name, session.app.command(session[:pic].path, :cget, '-image')
+        assert_equal 'photo', session.app.tcl_eval("image type #{icon.name}")
+
+        session.app.destroy
+      end
+    end
+  end
+
+  def test_add_on_an_unrealized_session_raises
+    assert_tk_app("ui.add before the session is realized should raise a clear error") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Incremental Realize Test') { |ui| ui.column(:list) }
+
+      assert_raises(Teek::UI::NotRealizedError) { session.add(:list) { |a| a.button(:item1) } }
+    end
+  end
+
+  def test_add_to_an_unknown_parent_name_raises
+    assert_tk_app("ui.add with a name that doesn't exist should raise a clear error") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Incremental Realize Test') { |ui| ui.column(:list) }
+      session.run_async
+      session.app.update
+
+      error = assert_raises(ArgumentError) { session.add(:nope) { |a| a.button(:item1) } }
+      assert_match(/nope/, error.message)
+
+      session.app.destroy
+    end
+  end
+end

data/test/test_keysyms.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+require 'teek/ui/keysyms'
+
+class TestKeysyms < Minitest::Test
+  def test_resolve_a_friendly_symbol_has_no_modifiers
+    modifiers, keysym = Teek::UI::Keysyms.resolve(:enter)
+
+    assert_equal [], modifiers
+    assert_equal 'Return', keysym
+  end
+
+  def test_resolve_covers_the_common_named_keys
+    {
+      escape: 'Escape', tab: 'Tab', space: 'space', backspace: 'BackSpace',
+      delete: 'Delete', up: 'Up', down: 'Down', left: 'Left', right: 'Right',
+      f1: 'F1', f12: 'F12',
+    }.each do |friendly, tk_keysym|
+      _, keysym = Teek::UI::Keysyms.resolve(friendly)
+      assert_equal tk_keysym, keysym, "#{friendly.inspect} should resolve to #{tk_keysym}"
+    end
+  end
+
+  def test_resolve_an_unknown_symbol_passes_through_as_the_literal_keysym
+    _, keysym = Teek::UI::Keysyms.resolve(:q)
+
+    assert_equal 'q', keysym
+  end
+
+  def test_resolve_a_single_modifier_string
+    modifiers, keysym = Teek::UI::Keysyms.resolve('Ctrl-s')
+
+    assert_equal ['Control'], modifiers
+    assert_equal 's', keysym
+  end
+
+  def test_resolve_a_multi_modifier_string
+    modifiers, keysym = Teek::UI::Keysyms.resolve('Ctrl-Shift-s')
+
+    assert_equal %w[Control Shift], modifiers
+    assert_equal 's', keysym
+  end
+
+  def test_resolve_a_modifier_string_with_a_friendly_base_key
+    modifiers, keysym = Teek::UI::Keysyms.resolve('Ctrl-Enter')
+
+    assert_equal ['Control'], modifiers
+    assert_equal 'Return', keysym
+  end
+
+  def test_patterns_for_the_common_case_is_a_single_pattern
+    patterns = Teek::UI::Keysyms.patterns_for(['Control'], 's')
+
+    assert_equal ['<Control-s>'], patterns
+  end
+
+  def test_patterns_for_no_modifiers
+    patterns = Teek::UI::Keysyms.patterns_for([], 'Return')
+
+    assert_equal ['<Return>'], patterns
+  end
+
+  def test_patterns_for_shift_tab_covers_the_iso_left_tab_gotcha
+    patterns = Teek::UI::Keysyms.patterns_for(['Shift'], 'Tab')
+
+    assert_includes patterns, '<Shift-Tab>'
+    assert_includes patterns, '<ISO_Left_Tab>'
+  end
+
+  def test_patterns_for_plain_tab_is_unaffected_by_the_shift_tab_special_case
+    patterns = Teek::UI::Keysyms.patterns_for([], 'Tab')
+
+    assert_equal ['<Tab>'], patterns
+  end
+end

data/test/test_layout.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../../test/tk_test_helper'
+
+class TestLayout < Minitest::Test
+  include TeekTestHelper
+
+  def test_column_stacks_children_top_to_bottom_with_the_given_gap
+    assert_tk_app("column should stack children vertically with `gap` pixels between them") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Layout Test') do |ui|
+        ui.column(:c, gap: 20) do |c|
+          c.button(:a, text: 'A')
+          c.button(:b, text: 'B')
+        end
+      end
+      session.run_async
+      session.app.update
+
+      a_bottom = session.app.winfo.rooty(session[:a].path) + session.app.winfo.height(session[:a].path)
+      b_top = session.app.winfo.rooty(session[:b].path)
+
+      assert_equal 20, b_top - a_bottom
+
+      session.app.destroy
+    end
+  end
+
+  def test_row_stacks_children_left_to_right_with_the_given_gap
+    assert_tk_app("row should stack children horizontally with `gap` pixels between them") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Layout Test') do |ui|
+        ui.row(:r, gap: 15) do |r|
+          r.button(:a, text: 'A')
+          r.button(:b, text: 'B')
+        end
+      end
+      session.run_async
+      session.app.update
+
+      a_right = session.app.winfo.rootx(session[:a].path) + session.app.winfo.width(session[:a].path)
+      b_left = session.app.winfo.rootx(session[:b].path)
+
+      assert_equal 15, b_left - a_right
+
+      session.app.destroy
+    end
+  end
+
+  def test_align_stretch_fills_the_cross_axis_in_a_column
+    assert_tk_app("align: :stretch should make a narrower child match the widest sibling's width") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Layout Test') do |ui|
+        ui.column(:c, align: :stretch) do |c|
+          c.button(:narrow, text: 'Go')
+          c.button(:wide, text: 'A Much Longer Button Label')
+        end
+      end
+      session.run_async
+      session.app.update
+
+      narrow_width = session.app.winfo.width(session[:narrow].path)
+      wide_width = session.app.winfo.width(session[:wide].path)
+
+      assert_equal wide_width, narrow_width
+
+      session.app.destroy
+    end
+  end
+
+  def test_align_start_does_not_stretch_children
+    assert_tk_app("without align: :stretch, a narrower child should keep its own natural width") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Layout Test') do |ui|
+        ui.column(:c) do |c|
+          c.button(:narrow, text: 'Go')
+          c.button(:wide, text: 'A Much Longer Button Label')
+        end
+      end
+      session.run_async
+      session.app.update
+
+      narrow_width = session.app.winfo.width(session[:narrow].path)
+      wide_width = session.app.winfo.width(session[:wide].path)
+
+      refute_equal wide_width, narrow_width
+
+      session.app.destroy
+    end
+  end
+
+  def test_pad_adds_a_margin_around_the_whole_stack
+    assert_tk_app("pad: should add space before the first child and after the last") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Layout Test') do |ui|
+        ui.column(:c, pad: 10) { |c| c.button(:only, text: 'Only') }
+      end
+      session.run_async
+      session.app.update
+
+      col_top = session.app.winfo.rooty(session[:c].path)
+      only_top = session.app.winfo.rooty(session[:only].path)
+
+      assert_equal 10, only_top - col_top
+
+      session.app.destroy
+    end
+  end
+
+  def test_spacer_with_grow_pushes_trailing_children_to_the_far_edge
+    assert_tk_app("a spacer should absorb leftover space, pushing what follows it to the bottom - the spring-row replacement") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Layout Test') do |ui|
+        ui.column(:c, height: 300) do |c|
+          c.button(:top, text: 'Top')
+          c.spacer
+          c.button(:bottom, text: 'Bottom')
+        end
+      end
+      session.run_async
+      # disable geometry propagation so the column keeps its explicit height
+      # instead of shrinking to fit its (currently tiny) content - this is
+      # test setup via the escape hatch, not part of the ported app code.
+      session.app.tcl_eval("pack propagate #{session[:c].path} 0")
+      session.app.update
+
+      col_bottom = session.app.winfo.rooty(session[:c].path) + session.app.winfo.height(session[:c].path)
+      bottom_button_bottom = session.app.winfo.rooty(session[:bottom].path) + session.app.winfo.height(session[:bottom].path)
+
+      # the bottom button should end close to the column's own bottom edge,
+      # not sitting right under the top button
+      assert_in_delta col_bottom, bottom_button_bottom, 2
+
+      top_bottom = session.app.winfo.rooty(session[:top].path) + session.app.winfo.height(session[:top].path)
+      bottom_top = session.app.winfo.rooty(session[:bottom].path)
+      assert_operator (bottom_top - top_bottom), :>, 100, "the spacer should have absorbed most of the leftover height"
+
+      session.app.destroy
+    end
+  end
+
+  def test_goldberg_control_panel_prototype_realizes_with_only_the_layout_dsl
+    assert_tk_app("goldberg's control panel column should realize correctly using only column/gap/align/spacer") do
+      require 'teek/ui'
+
+      speed = nil
+      session = Teek::UI.app(title: 'Layout Test') do |ui|
+        speed = ui.var(5)
+        ui.column(:ctrl, gap: 4, align: :stretch, pad: 5) do |c|
+          c.button(:start, text: 'Start')
+          c.checkbox(:pause, text: 'Pause')
+          c.button(:step, text: 'Single Step')
+          c.button(:bstep, text: 'Big Step')
+          c.button(:reset, text: 'Reset')
+          c.checkbox(:details, text: 'Details')
+          c.spacer
+          c.text_box(:msg_entry)
+          c.slider(:speed_scale, from: 1, to: 10, bind: speed)
+          c.button(:about, text: 'About')
+        end
+      end
+      session.run_async
+      session.app.update
+
+      %i[start pause step bstep reset details msg_entry speed_scale about].each do |name|
+        path = session[name].path
+        assert session.app.winfo.exists?(path), "#{name} should exist"
+        assert session.app.winfo.ismapped?(path), "#{name} should be mapped/visible"
+      end
+
+      # every widget stretches to the column's own width (align: :stretch)
+      widths = %i[start pause about].map { |n| session.app.winfo.width(session[n].path) }
+      assert_equal 1, widths.uniq.length
+
+      session.app.destroy
+    end
+  end
+end

data/test/test_lazy_realize.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+require 'teek/ui/document'
+require 'teek/ui/realizer'
+require 'teek/ui/event_binding'
+
+# Headless coverage of the lazy: true skip/on-demand-realize mechanism
+# itself, isolated from Handle (which stays a thin, private wrapper
+# around this - see test_screens_realtk.rb/test_modal_stack_realtk.rb
+# for the real-Tk, public-facing behavior through ui.screens/ui.modal)
+# and from real Tk entirely - built by hand against Document/Node/
+# Realizer's own public API, using the shared FakeApp (support/fake_app.rb)
+# to record what Realizer would have created, the same way test_screens.rb
+# does for Screens' own reveal/conceal calls.
+class TestLazyRealize < Minitest::Test
+  def build_host_and_picker(picker_children: [])
+    document = Teek::UI::Document.new
+    host = document.create(type: :panel, name: :host)
+    document.root.add_child(host)
+    picker = document.create(type: :panel, name: :picker)
+    picker.lazy = true
+    host.add_child(picker)
+    picker_children.each { |child| picker.add_child(child) }
+    [document, host, picker]
+  end
+
+  def test_a_lazy_node_is_not_created_by_the_initial_realize
+    document, _host, picker = build_host_and_picker
+    app = FakeApp.new
+
+    Teek::UI::Realizer.new(app, document).realize
+
+    assert_nil picker.realized
+    refute app.calls.any? { |(args, _)| args.include?('.host.picker') }
+  end
+
+  def test_a_lazy_nodes_own_children_are_also_skipped_by_the_initial_realize
+    document, _host, picker = build_host_and_picker
+    load_node = document.create(type: :button, name: :load, opts: { text: 'Load' })
+    picker.add_child(load_node)
+    app = FakeApp.new
+
+    Teek::UI::Realizer.new(app, document).realize
+
+    assert_nil load_node.realized
+    refute app.calls.any? { |(args, _)| args.include?('.host.picker.load') }
+  end
+
+  def test_a_non_lazy_sibling_still_realizes_normally_next_to_a_lazy_one
+    document, host, _picker = build_host_and_picker
+    go = document.create(type: :button, name: :go, opts: { text: 'Go' })
+    host.add_child(go)
+    app = FakeApp.new
+
+    Teek::UI::Realizer.new(app, document).realize
+
+    refute_nil go.realized
+    assert_equal '.host.go', go.realized.path
+    assert app.calls.any? { |(args, _)| args.include?('.host.go') }
+  end
+
+  def test_arrange_children_does_not_choke_on_a_still_unrealized_lazy_sibling
+    document, host, _picker = build_host_and_picker
+    go = document.create(type: :button, name: :go, opts: { text: 'Go' })
+    host.add_child(go)
+    app = FakeApp.new
+
+    # link() (which arrange_children is part of) walks the WHOLE tree
+    # after create finishes - reaching this line without a NoMethodError
+    # on a nil .realized for the still-lazy :picker sibling IS the
+    # assertion (see Realizer#arrange_children's own lazy-aware filter).
+    Teek::UI::Realizer.new(app, document).realize
+
+    assert app.calls.any? { |(args, kwargs)| args == [:pack, '.host.go'] || (args.first == :pack && kwargs.empty?) }
+  end
+
+  def test_realize_subtree_realizes_a_lazy_node_and_its_own_children_on_demand
+    document, host, picker = build_host_and_picker
+    load_node = document.create(type: :button, name: :load, opts: { text: 'Load' })
+    picker.add_child(load_node)
+    app = FakeApp.new
+    Teek::UI::Realizer.new(app, document).realize
+
+    Teek::UI::Realizer.new(app, document).realize_subtree(picker, host)
+
+    refute_nil picker.realized
+    assert_equal '.host.picker', picker.realized.path
+    refute_nil load_node.realized
+    assert_equal '.host.picker.load', load_node.realized.path
+    assert app.calls.any? { |(args, _)| args.include?('.host.picker') }
+    assert app.calls.any? { |(args, _)| args.include?('.host.picker.load') }
+  end
+
+  def test_realize_subtree_wires_events_queued_before_realize
+    document, host, picker = build_host_and_picker
+    fired = false
+    picker.events << Teek::UI::EventBinding.new(event: '<Button-1>', handler: -> { fired = true }, subs: [])
+    app = FakeApp.new
+    Teek::UI::Realizer.new(app, document).realize
+
+    Teek::UI::Realizer.new(app, document).realize_subtree(picker, host)
+
+    bound = app.binds.find { |b| b[:path] == '.host.picker' && b[:event] == '<Button-1>' }
+    refute_nil bound, "the event queued on the lazy node before realize should get wired once it's realized"
+    bound[:block].call
+    assert fired
+  end
+
+  def test_a_later_arrange_children_call_picks_up_a_now_realized_former_lazy_sibling
+    document, host, picker = build_host_and_picker
+    app = FakeApp.new
+    Teek::UI::Realizer.new(app, document).realize
+    Teek::UI::Realizer.new(app, document).realize_subtree(picker, host)
+    app.calls.clear
+
+    # mirrors Session#add adding a further sibling to :host later - its
+    # own realize_subtree re-arranges ALL of host's children, which by
+    # now includes the no-longer-lazy :picker (see Realizer#arrange_children's
+    # "lazy? && !realized" - not bare "lazy?" - filter).
+    another = document.create(type: :button, name: :another, opts: { text: 'Another' })
+    host.add_child(another)
+    Teek::UI::Realizer.new(app, document).realize_subtree(another, host)
+
+    assert app.calls.any? { |(args, _)| args.include?('.host.picker') },
+      "the now-realized :picker should be re-arranged alongside the new sibling, not skipped forever"
+  end
+end