teek-ui 0.1.0

data/lib/teek/ui/widget_types/text_area.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(type: :text_area, tk_command: 'text', natively_scrollable: true)
+)

data/lib/teek/ui/widget_types/text_box.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(type: :text_box, tk_command: 'ttk::entry', bind_option: :textvariable)
+)

data/lib/teek/ui/widget_types/tree.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+# `tree` and `table` are two DSL names over the same Tk widget
+# (ttk::treeview, used with/without -show tree) - see table.rb.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(type: :tree, tk_command: 'ttk::treeview', natively_scrollable: true)
+)

data/lib/teek/ui/widget_types/window.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+module Teek
+  module UI
+    # @api private
+    #
+    # A freshly created :window's post-creation setup: title/geometry/
+    # resizable setup, transient-to-parent, the macOS shared-menubar quirk
+    # (each platform other than macOS gets its own menu bar per window;
+    # macOS has a single app-wide menu bar, so without this a new window
+    # falls back to Tk's default "wish" menu instead of the parent's), and
+    # withdrawn by default - shown explicitly via Handle#show. Registered
+    # as :window's own `post_create:` below.
+    module WindowRealize
+      def self.post_create(app, node, path, parent_path)
+        opts = node.opts
+        window = app.window(path)
+
+        window.set_title(opts[:title]) if opts[:title]
+        window.set_geometry(opts[:geometry]) if opts[:geometry]
+        if opts.key?(:resizable)
+          pair = opts[:resizable]
+          width, height = pair.is_a?(Array) ? pair : [pair, pair]
+          window.set_resizable(width, height)
+        end
+        app.command(:wm, :transient, path, parent_path) unless opts[:transient] == false
+        share_macos_menu(app, path, parent_path) if Teek.platform.darwin?
+        window.withdraw
+      end
+
+      def self.share_macos_menu(app, path, parent_path)
+        parent_menu = app.command(parent_path, :cget, '-menu')
+        app.command(path, :configure, menu: parent_menu) unless parent_menu.nil? || parent_menu.empty?
+      rescue Teek::TclError
+        nil
+      end
+    end
+  end
+end
+
+# A toplevel - placed by the window manager, never pack/grid-managed by
+# its nominal parent.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :window, tk_command: 'toplevel', leaf: false, arranged: false,
+    post_create: Teek::UI::WindowRealize.method(:post_create)
+  )
+)

data/lib/teek/ui/widget_types.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative 'widget_type'
+require_relative 'widget_validators'
+
+module Teek
+  module UI
+    # @api private
+    #
+    # Central registry of {WidgetType} descriptors, mirroring
+    # {Teek::CommandInterceptors}'s own register/for_type shape - one
+    # registered descriptor per node type is the single source of truth
+    # {WidgetDSL}, {Realizer}, and {Validator} each dispatch to for that
+    # type's own build/realize/validate behavior.
+    #
+    # Unlike {Teek::CommandInterceptors} (consulted per-call with a type
+    # already in hand) or {WidgetValidators} (many validators can share one
+    # type), exactly one descriptor owns a given type here, and consumers
+    # need the full set up front to drive codegen - so this adds two things
+    # CommandInterceptors doesn't need: {.each} (enumerate every registered
+    # type) and {.on_register} (subscribe to every past AND future
+    # registration, so load order between this file and a consumer like
+    # {WidgetDSL} never matters).
+    #
+    # A descriptor's +validator:+ (see {WidgetType}) is forwarded into
+    # {WidgetValidators} right here, at registration time, so it's
+    # dispatched through the exact same +WidgetValidators.for_type+ call
+    # every other validator goes through - {Validator} itself carries no
+    # awareness of descriptors at all.
+    class WidgetTypes
+      class << self
+        # @param widget_type [WidgetType]
+        # @return [WidgetType] +widget_type+, for chaining
+        # @raise [ArgumentError] if +widget_type.type+ is already registered
+        def register(widget_type)
+          key = widget_type.type.to_s
+          if types.key?(key)
+            raise ArgumentError, "widget type :#{widget_type.type} is already registered"
+          end
+
+          types[key] = widget_type
+          if widget_type.validator
+            WidgetValidators.register(widget_type.type) { |*args| widget_type.validator.call(*args) }
+          end
+          callbacks.each { |callback| callback.call(widget_type) }
+
+          widget_type
+        end
+
+        # @param type [Symbol, String]
+        # @return [WidgetType, nil]
+        def for_type(type)
+          types[type.to_s]
+        end
+
+        # @yieldparam widget_type [WidgetType]
+        # @return [Enumerator] if no block given
+        def each(&block)
+          return enum_for(:each) unless block
+
+          types.each_value(&block)
+        end
+
+        # Subscribes +block+ to every type registered from now on, and
+        # immediately replays every type already registered - so a
+        # subscriber (namely {WidgetDSL}'s own codegen) sees every type
+        # regardless of whether it loaded before or after this file
+        # populated its own built-ins.
+        # @yieldparam widget_type [WidgetType]
+        # @return [void]
+        def on_register(&block)
+          types.each_value(&block)
+          callbacks << block
+        end
+
+        private
+
+        def types
+          @types ||= {}
+        end
+
+        def callbacks
+          @callbacks ||= []
+        end
+      end
+    end
+  end
+end
+
+require_relative 'widget_types/divider'
+require_relative 'widget_types/text_box'
+require_relative 'widget_types/text_area'
+require_relative 'widget_types/label'
+require_relative 'widget_types/button'
+require_relative 'widget_types/checkbox'
+require_relative 'widget_types/radio'
+require_relative 'widget_types/slider'
+require_relative 'widget_types/dropdown'
+require_relative 'widget_types/number_box'
+require_relative 'widget_types/list'
+require_relative 'widget_types/table'
+require_relative 'widget_types/tree'
+require_relative 'widget_types/progress'
+require_relative 'widget_types/panel'
+require_relative 'widget_types/group'
+require_relative 'widget_types/canvas'
+require_relative 'widget_types/window'
+require_relative 'widget_types/column'
+require_relative 'widget_types/row'
+require_relative 'widget_types/spacer'
+require_relative 'widget_types/grid'
+require_relative 'widget_types/scrollable'
+require_relative 'widget_types/tabs'
+require_relative 'widget_types/tab'
+require_relative 'widget_types/split'
+require_relative 'widget_types/pane'
+require_relative 'widget_types/menu_bar'
+require_relative 'widget_types/context_menu'
+require_relative 'widget_types/menu_item'
+require_relative 'widget_types/menu_checkbox'
+require_relative 'widget_types/menu_radio'

data/lib/teek/ui/widget_validators.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    # @api private
+    #
+    # Registry of per-node-type validators, mirroring {Teek::CommandInterceptors}'
+    # own register(type, ...)/for_type(type) shape. {Validator} (the
+    # coordinator) walks the whole {Document} exactly once; at each node it
+    # looks up +WidgetValidators.for_type(node.type)+ and calls every
+    # validator registered there.
+    #
+    # A registered validator receives +(node, parent, document, errors)+ and
+    # must APPEND problem strings to +errors+ - it must never raise itself.
+    # Unlike a {Teek::CommandInterceptors} entry (which "claims" a call and
+    # returns its result), a widget validator has nothing to return and
+    # nothing to claim exclusively - multiple validators for the same type
+    # can coexist freely, and there's no ambiguity to detect.
+    #
+    # Registering a validator for a type is purely additive: a custom or
+    # third-party widget can call {.register} to get its own contract
+    # checked without editing this file or {Validator}, the same way a
+    # custom widget can register a {Teek::CommandInterceptors} entry without
+    # editing +teek.rb+.
+    class WidgetValidators
+      class << self
+        # @param type [Symbol, String] the node type this validator applies to
+        # @yieldparam node [Node]
+        # @yieldparam parent [Node, nil]
+        # @yieldparam document [Document]
+        # @yieldparam errors [Array<String>]
+        # @return [void]
+        def register(type, &block)
+          validators[type.to_s] << block
+        end
+
+        # @param type [Symbol, String]
+        # @return [Array<Proc>] every validator registered for +type+, in
+        #   registration order - empty if none are
+        def for_type(type)
+          validators[type.to_s]
+        end
+
+        # Shared node-describing helper every validator's error messages use
+        # ("#label(:name)" or "an unnamed #label") - kept here rather than
+        # duplicated per validator file, since every one of them needs it.
+        # @param node [Node, nil]
+        # @return [String]
+        def describe(node)
+          return 'the document root' unless node
+          node.name ? "##{node.type}(:#{node.name})" : "an unnamed ##{node.type}"
+        end
+
+        private
+
+        def validators
+          @validators ||= Hash.new { |h, k| h[k] = [] }
+        end
+      end
+    end
+  end
+end

data/lib/teek/ui.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "teek"
+require_relative "ui/version"
+require_relative "ui/event_binding"
+require_relative "ui/session"
+require_relative "ui/tree_inspector"
+
+module Teek
+  # A DSL for building teek (Tk) apps - sugar over teek, not a wall around it.
+  # Everything here compiles down to plain teek calls, and every handle keeps
+  # an escape hatch back to the underlying {Teek::App}.
+  module UI
+    class << self
+      # @return [Boolean] whether a bare list/text_area/table/tree
+      #   auto-attaches a scrollbar with no `ui.scrollable` wrapper needed -
+      #   true by default. Three levels can override it, most specific
+      #   wins: a widget's own `scroll:` option, then `Teek::UI.app`'s own
+      #   `scroll:`, then this global default.
+      attr_accessor :auto_scroll
+
+      # @return [Boolean] the same default, but for canvas specifically -
+      #   false by default, since a canvas is as often fixed drawing as
+      #   scrollable content, unlike the other native types.
+      attr_accessor :auto_scroll_canvas
+    end
+    self.auto_scroll = true
+    self.auto_scroll_canvas = false
+
+    # Build an app. Constructs a {Session} (Tk-free - no {Teek::App} exists
+    # yet), yields it to the block, and returns that same session so
+    # `.run`/`.run_async` can be chained directly off the call. The
+    # underlying app is created lazily, at realize (see {Session#realize}).
+    #
+    # @param title [String, nil] window title
+    # @param scroll [Boolean, nil] app-wide override for whether native
+    #   scrollable widgets auto-attach a scrollbar - between a widget's own
+    #   `scroll:` (most specific) and {.auto_scroll}/{.auto_scroll_canvas}
+    #   (global default). `nil` (the default) defers straight to the global.
+    # @param app_opts [Hash] forwarded to {Teek::App.new} at realize (e.g. +debug:+, +track_widgets:+)
+    # @yieldparam ui [Session]
+    # @return [Session]
+    #
+    # @example
+    #   Teek::UI.app(title: "Hello") do |ui|
+    #     # widget/layout DSL calls go here
+    #   end.run
+    def self.app(title: nil, scroll: nil, **app_opts, &block)
+      session = Session.new(title: title, scroll: scroll, app_opts: app_opts)
+      block.call(session) if block
+      session
+    end
+  end
+end

data/teek-ui.gemspec

@@ -0,0 +1,24 @@
+require_relative "lib/teek/ui/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "teek-ui"
+  spec.version       = Teek::UI::VERSION
+  spec.authors       = ["James Cook"]
+  spec.email         = ["jcook.rubyist@gmail.com"]
+
+  spec.summary       = "The friendly way to build Tk apps in Ruby"
+  spec.description   = "Declarative widgets, layout, events, and reactive state on top of teek"
+  spec.homepage      = "https://github.com/jamescook/teek"
+  spec.licenses      = ["MIT"]
+
+  spec.files         = Dir.glob("{lib,test}/**/*").select { |f|
+                         File.file?(f) && f !~ /\.log$/
+                       } + %w[teek-ui.gemspec CHANGELOG.md README.md]
+  spec.require_paths = ["lib"]
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.add_dependency "teek", "~> 0.3"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 6.0"
+end

data/test/support/fake_app.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# A minimal stand-in for Teek::App, for headless tests that need
+# something Realizer/Handle-shaped without a real Tk interpreter -
+# Realizer#create/#link/#realize_subtree only ever call .command/.bind/
+# .on_close (and, for a menu/window handle, .popup_menu/.window) on
+# whatever app they're given, so a fake recording every call is enough
+# to assert on exactly what WOULD have happened against real Tk. Shared
+# across every headless suite that needs one, so there's a single
+# definition to keep in sync with the real Teek::App/Teek::Window
+# signatures (see test_fake_app_contract.rb) rather than one per file.
+FakeWindow = Struct.new(:path, :modal_calls, :grab_releases) do
+  def initialize(path, modal_calls = [], grab_releases = [])
+    super
+  end
+
+  def modal(global: false, &block)
+    modal_calls << { global: global }
+    block.call if block
+  end
+
+  def grab_release
+    grab_releases << true
+  end
+end
+
+FakeApp = Struct.new(:calls, :binds, :on_closes, :popups, :windows) do
+  def initialize(calls = [], binds = [], on_closes = [], popups = [], windows = [])
+    super
+  end
+
+  def command(cmd, *args, **kwargs)
+    calls << [[cmd, *args], kwargs]
+    nil
+  end
+
+  def bind(path, event, *subs, &block)
+    binds << { path: path, event: event, subs: subs, block: block }
+    nil
+  end
+
+  def on_close(window:, &block)
+    on_closes << { window: window, block: block }
+    nil
+  end
+
+  def popup_menu(menu, x:, y:, entry: nil)
+    popups << { menu: menu, x: x, y: y, entry: entry }
+    nil
+  end
+
+  def window(path = '.')
+    win = FakeWindow.new(path)
+    windows << win
+    win
+  end
+end

data/test/test_busy.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../../test/tk_test_helper'
+
+# session.busy is a thin, realize-only delegation to Teek::App#busy (see
+# teek core's own test/test_busy.rb for the underlying busy-cursor
+# set/clear behavior, including exception safety). What's new to verify
+# at this layer: the delegation itself (window:, block value, exception
+# safety all still work through Session), and that it raises before
+# realize like every other realize-only Session method.
+class TestBusy < Minitest::Test
+  include TeekTestHelper
+
+  def test_busy_raises_before_realize
+    assert_tk_app("session.busy should raise a clear error before realize, not queue") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Busy Test')
+
+      assert_raises(Teek::UI::NotRealizedError) { session.busy { } }
+    end
+  end
+
+  def test_busy_sets_and_clears_busy_state_and_returns_the_blocks_value
+    assert_tk_app("session.busy should show the busy cursor for the duration of the block, then clear it") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Busy Test')
+      session.run_async
+      session.app.update
+
+      was_busy = nil
+      result = session.busy {
+        was_busy = session.app.tcl_eval('tk busy status .') == '1'
+        42
+      }
+
+      assert was_busy, "expected the window to be busy during the block"
+      assert_equal '0', session.app.tcl_eval('tk busy status .')
+      assert_equal 42, result
+
+      session.app.destroy
+    end
+  end
+
+  def test_busy_clears_on_exception
+    assert_tk_app("session.busy should clear the busy cursor even if the block raises") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Busy Test')
+      session.run_async
+      session.app.update
+
+      assert_raises(RuntimeError) { session.busy { raise 'boom' } }
+      assert_equal '0', session.app.tcl_eval('tk busy status .')
+
+      session.app.destroy
+    end
+  end
+
+  def test_busy_works_on_a_specific_window
+    assert_tk_app("session.busy's window: should target that window, not just the root") do
+      require 'teek/ui'
+
+      session = Teek::UI.app(title: 'Busy Test') { |ui| ui.window(:extra) }
+      session.run_async
+      session[:extra].show
+      session.app.update
+      extra_path = session[:extra].path
+
+      was_busy = nil
+      session.busy(window: extra_path) {
+        was_busy = session.app.tcl_eval("tk busy status #{extra_path}") == '1'
+      }
+
+      assert was_busy, "expected the extra window to be busy during the block"
+
+      session.app.destroy
+    end
+  end
+end