teek-ui 0.1.0

data/lib/teek/ui/canvas_item.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require_relative 'mouse_events'
+
+module Teek
+  module UI
+    # A handle onto one or more canvas items, addressed by Tk's own
+    # tagOrId - either the numeric id a `create` call returns (a single
+    # item) or an arbitrary tag string (every item currently carrying it,
+    # zero or more). Every method here is exactly that uniform - Tk's own
+    # canvas command already treats a tag and an id identically for
+    # move/coords/itemconfigure/delete/stacking/scale, so a shared tag is
+    # addressable as a group with no separate "group handle" type: get one
+    # via a shape-creation method (see {Handle#line} and friends, a
+    # single-item handle) or {Handle#tagged} (an existing tag, whatever it
+    # currently matches).
+    class CanvasItem
+      # @return [String] the tagOrId this handle addresses
+      attr_reader :tag_or_id
+
+      # @api private
+      def initialize(app, canvas_path, tag_or_id)
+        @app = app
+        @canvas_path = canvas_path
+        @tag_or_id = tag_or_id.to_s
+      end
+
+      # @return [String] the canvas's own path, marked past the point a
+      #   real Tk path stops applying - an item/tag has no independent Tk
+      #   path of its own, only the canvas does. +!+ is illegal in a Tk
+      #   path segment, so handing this to a raw Tk command fails loudly
+      #   (an "invalid command name" Tcl error) instead of silently
+      #   misbehaving - the same marked-address shape
+      #   {MenuEntryAddressing#virtual_path} uses for a menu entry, the
+      #   other kind of thing with no Tk path of its own.
+      def virtual_path
+        "#{@canvas_path}!#{@tag_or_id}"
+      end
+
+      # Move relative to the current position.
+      # @param dx [Numeric]
+      # @param dy [Numeric]
+      # @return [self]
+      def move(dx, dy)
+        @app.command(@canvas_path, :move, @tag_or_id, dx, dy)
+        self
+      end
+
+      # @return [Array<Float>] the current coordinate list
+      def points
+        result = @app.command(@canvas_path, :coords, @tag_or_id)
+        @app.split_list(result).map(&:to_f)
+      end
+      alias_method :coords, :points
+
+      # Replace the coordinate list outright (as opposed to {#move}'s
+      # relative shift).
+      # @param new_coords [Array<Numeric>] flat or nested (e.g.
+      #   +[[x1, y1], [x2, y2]]+) - flattened either way
+      # @return [void]
+      def points=(new_coords)
+        @app.command(@canvas_path, :coords, @tag_or_id, *new_coords.flatten)
+      end
+      alias_method :coords=, :points=
+
+      # Mutate several item options at once.
+      # @param opts [Hash] item options, e.g. +fill: 'red'+
+      # @return [self]
+      def configure(**opts)
+        @app.command(@canvas_path, :itemconfigure, @tag_or_id, **opts)
+        self
+      end
+
+      # Read back a single item option - +item[:fill]+.
+      # @param opt [Symbol, String] e.g. +:fill+
+      # @return [String]
+      def [](opt)
+        @app.command(@canvas_path, :itemcget, @tag_or_id, "-#{opt}")
+      end
+
+      # Set a single item option - +item[:fill] = 'red'+. Shorthand for
+      # +configure(opt => value)+ when there's only one to change.
+      # @param opt [Symbol, String] e.g. +:fill+
+      # @param value [Object]
+      # @return [Object] +value+
+      def []=(opt, value)
+        configure(opt => value)
+        value
+      end
+
+      # Remove the item(s) from the canvas.
+      # @return [nil]
+      def delete
+        @app.command(@canvas_path, :delete, @tag_or_id)
+        nil
+      end
+
+      # Bring to the front of the stacking order (drawn last, on top of
+      # everything), or - given +above+ - just in front of that one
+      # item/tag instead of all the way to the front.
+      # @param above [CanvasItem, String, nil]
+      # @return [self]
+      def bring_to_front(above = nil)
+        args = above ? [resolve(above)] : []
+        @app.command(@canvas_path, :raise, @tag_or_id, *args)
+        self
+      end
+      # Tk's own name for {#bring_to_front} - not plain +raise+, which
+      # would silently shadow +Kernel#raise+ on every CanvasItem (a bare
+      # +raise+ call from inside this class, now or later, would call
+      # THIS method instead of actually raising - a real, silent
+      # footgun, not just a style concern).
+      alias_method :tk_raise, :bring_to_front
+
+      # Send to the back of the stacking order (drawn first, under
+      # everything), or - given +below+ - just behind that one item/tag
+      # instead of all the way to the back.
+      # @param below [CanvasItem, String, nil]
+      # @return [self]
+      def send_to_back(below = nil)
+        args = below ? [resolve(below)] : []
+        @app.command(@canvas_path, :lower, @tag_or_id, *args)
+        self
+      end
+      alias_method :lower, :send_to_back
+
+      # Scale coordinates relative to a fixed point.
+      # @param ox [Numeric] x origin scaling is relative to
+      # @param oy [Numeric] y origin scaling is relative to
+      # @param sx [Numeric] x scale factor
+      # @param sy [Numeric] y scale factor
+      # @return [self]
+      def scale(ox, oy, sx, sy)
+        @app.command(@canvas_path, :scale, @tag_or_id, ox, oy, sx, sy)
+        self
+      end
+
+      # @return [Array<Float>, nil] +[x1, y1, x2, y2]+ bounding box, or
+      #   +nil+ if nothing currently matches {#tag_or_id}
+      def bounds
+        result = @app.command(@canvas_path, :bbox, @tag_or_id)
+        result.empty? ? nil : @app.split_list(result).map(&:to_f)
+      end
+      alias_method :bbox, :bounds
+
+      # @return [Boolean] whether any item currently matches {#tag_or_id} -
+      #   always true for a single-item handle from a creation method
+      #   (the item exists until {#delete}d), meaningful for a {Handle#tagged}
+      #   group that may currently match zero items
+      def exists?
+        !@app.command(@canvas_path, :find, :withtag, @tag_or_id).empty?
+      end
+
+      # Fires on a left click, only when the click lands on this specific
+      # item/tag - other items on the same canvas are untouched. Wired
+      # immediately, via the canvas's own `bind` subcommand (Tk has no
+      # per-item widget path to bind a plain `bind` against) - unlike
+      # {Handle}, a CanvasItem only ever exists post-realize, so there's no
+      # queue-before-realize phase to worry about here.
+      # @yield called with no arguments
+      # @return [self]
+      def on_click(&block)
+        bind_item_event('<Button-1>', block)
+        self
+      end
+
+      # Fires on a right click, however the platform spells it - see
+      # {MouseEvents::RIGHT_CLICK_EVENTS}. Either handle it yourself with a
+      # block, or hand it a `:menu`/`:context_menu` handle to pop up at the
+      # click's screen position - not both.
+      # @param menu [Handle, nil] a `:menu` or `:context_menu` handle to tk_popup
+      # @yield called with no arguments (only when +menu+ isn't given)
+      # @return [self]
+      # @raise [ArgumentError] if given neither or both, or +menu+ isn't a menu handle
+      def on_right_click(menu = nil, &block)
+        if menu && block
+          raise ArgumentError, "on_right_click takes either a menu handle or a block, not both"
+        elsif menu
+          unless MouseEvents::MENU_HANDLE_TYPES.include?(menu.type)
+            raise ArgumentError, "on_right_click(menu) needs a :menu or :context_menu handle (got a :#{menu.type})"
+          end
+
+          popup = lambda do |root_x, root_y|
+            @app.popup_menu(menu.path, x: root_x, y: root_y)
+          end
+          MouseEvents::RIGHT_CLICK_EVENTS.each { |event| bind_item_event(event, popup, subs: %i[root_x root_y]) }
+        elsif block
+          MouseEvents::RIGHT_CLICK_EVENTS.each { |event| bind_item_event(event, block) }
+        else
+          raise ArgumentError, "on_right_click needs either a menu handle or a block"
+        end
+        self
+      end
+
+      # Fires while dragging this item (left button held down and moving).
+      # Delivers Integer x/y already converted through the canvas's own
+      # canvasx/canvasy, same as {Handle#on_drag} does when bound to a
+      # canvas - callers never have to remember to do that themselves.
+      # @yield [x, y] Integer coordinates
+      # @return [self]
+      def on_drag(&block)
+        wrapped = lambda do |raw_x, raw_y|
+          x, y = canvas_xy(raw_x, raw_y)
+          block.call(x, y)
+        end
+        bind_item_event('<B1-Motion>', wrapped, subs: %i[x y])
+        self
+      end
+
+      # Makes this item movable by mouse drag, with zero coordinate math
+      # of your own - press and drag it around the canvas, it follows the
+      # pointer. Binds `<Button-1>` (to capture the starting position) and
+      # `<B1-Motion>` (to shift {#move} by the delta each tick) on this
+      # item/tag, replacing any {#on_click}/{#on_drag} binding already set
+      # on it, the same way any two binds on the same item/event replace
+      # each other in Tk.
+      # @yield [x, y] optional - the item's new pointer-relative position
+      #   (same Integer canvasx/canvasy coordinates {#on_drag} delivers)
+      #   after each move, e.g. to react to where it's been dragged to
+      # @return [self]
+      def draggable(&block)
+        last = nil
+
+        press = lambda do |raw_x, raw_y|
+          last = canvas_xy(raw_x, raw_y)
+        end
+        bind_item_event('<Button-1>', press, subs: %i[x y])
+
+        drag = lambda do |raw_x, raw_y|
+          x, y = canvas_xy(raw_x, raw_y)
+          move(x - last[0], y - last[1])
+          last = [x, y]
+          block.call(x, y) if block
+        end
+        bind_item_event('<B1-Motion>', drag, subs: %i[x y])
+
+        self
+      end
+
+      private
+
+      def canvas_xy(raw_x, raw_y)
+        x = @app.command(@canvas_path, :canvasx, raw_x).to_f.round
+        y = @app.command(@canvas_path, :canvasy, raw_y).to_f.round
+        [x, y]
+      end
+
+      def resolve(item)
+        item.is_a?(CanvasItem) ? item.tag_or_id : item.to_s
+      end
+
+      # Canvas items have no widget path of their own, so binding one of
+      # their events goes through the canvas's own `bind` subcommand
+      # (`$canvas bind tagOrId <event> script`) rather than the generic
+      # `bind` Tk command {Teek::App#bind} wraps - a different Tcl command
+      # entirely, needing its own callback wiring. {Teek::CanvasBindInterceptor}
+      # (registered for the `canvas` widget type) already reconciles the
+      # callback this registers when the item's tag/id stops matching
+      # anything, same leak-safety {Teek::App#bind} gives ordinary widget
+      # events - nothing extra to do here for that. +subs+ reuses
+      # {Teek::App::BIND_SUBS} for the same symbol -> %-code vocabulary
+      # {Teek::App#bind} already uses, so e.g. +:x+/+:root_x+ mean the same
+      # thing here as everywhere else.
+      def bind_item_event(event, handler, subs: [])
+        tcl_subs = subs.map { |s| Teek::App::BIND_SUBS.fetch(s) }
+        @app.command(@canvas_path, :bind, @tag_or_id, event, proc { |*args| handler.call(*args) }, *tcl_subs)
+      end
+    end
+  end
+end

data/lib/teek/ui/component_handle.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'handle'
+
+module Teek
+  module UI
+    # A component's own public surface, returned by {WidgetDSL#component} -
+    # the disciplined way a parent reaches a child's named widgets without
+    # falling back to the flat, global `ui[]` index (which never sees into
+    # a component's scope at all - see {WidgetDSL#[]}). Wraps a
+    # (document, scope) pair and resolves names exactly the way `ui[]`
+    # already does from inside the component's own block, just usable from
+    # outside it - the parent addresses children through this facade, not
+    # through `@document.find` or a captured {Node}.
+    class ComponentHandle
+      # @api private
+      def initialize(document, scope)
+        @document = document
+        @scope = scope
+      end
+
+      # @param name [Symbol]
+      # @return [Handle, nil] +nil+ if this component never declared
+      #   +name+ - same nil-on-miss convention as {WidgetDSL#[]}
+      def handle(name)
+        node = @document.find(name, scope: @scope)
+        node && Handle.new(node)
+      end
+      alias_method :[], :handle
+    end
+  end
+end

data/lib/teek/ui/document.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative 'node'
+require_relative 'scope'
+require_relative 'event_bus'
+
+module Teek
+  module UI
+    # The build-phase tree: an unattached root {Node} plus a name index
+    # (Symbol -> Node). Plain Ruby, no Tk - building and traversing a
+    # Document never touches an interpreter, which is what makes the DSL
+    # headless-testable.
+    #
+    # Document only constructs and indexes nodes; it has no opinion on tree
+    # shape (which node is whose parent) - the build surface decides that by
+    # calling {Node#add_child} itself, so Document stays reusable underneath
+    # whatever parent-tracking scheme the builder uses.
+    class Document
+      # @return [Node] the tree's root - starts with no children
+      attr_reader :root
+
+      def initialize
+        @root = Node.new(type: :root, document: self)
+        @index = {}
+        @next_auto_key = 0
+        @used_segments = {}
+        @events = EventBus.new
+      end
+
+      # @api private
+      #
+      # A minimal, always-on, generic build-event hook - {Node#add_child}
+      # notifies +:append+; the build stack's own push/pop
+      # ({WidgetDSL#push_stack}/{WidgetDSL#pop_stack}) notify +:push+/
+      # +:pop+. Document has no idea what (if anything) is listening, or
+      # why - it's a plain {EventBus}, same mechanism {Session}'s own
+      # public +ui.on+/+ui.emit+ already uses, just private and scoped to
+      # build-time instrumentation instead of app events. With nothing
+      # subscribed (the overwhelmingly common case), {#notify} costs one
+      # hash lookup into an empty list - not something a normal build
+      # needs to think about. See {TreeInspector}, the one built-in
+      # subscriber.
+      # @param event [Symbol]
+      # @yield see {EventBus#on}
+      # @return [Proc] see {EventBus#on}
+      def subscribe(event, &block)
+        @events.on(event, &block)
+      end
+
+      # @api private - see {#subscribe}
+      # @param event [Symbol]
+      # @param args [Array] forwarded to every subscriber
+      # @return [void]
+      def notify(event, *args)
+        @events.emit(event, *args)
+      end
+
+      # Construct a node and register it under its name (if any), scoped
+      # to +scope+ - the same name used in two different scopes indexes
+      # as two distinct entries, so a component's local +:save+ never
+      # collides with another component's (or the top level's) own
+      # +:save+. Does NOT attach it to any parent - the caller does that
+      # with {Node#add_child}, so Document never needs to know about a
+      # current-parent stack.
+      #
+      # The node's own +name+/+key+ stay bare/unqualified - only this
+      # index is scope-aware. A node's real Tk path is already distinct
+      # per scope with no help needed here, since it's built from the
+      # parent chain ({Realizer#allocate_path}), and two components'
+      # subtrees are never siblings of themselves.
+      # @param type [Symbol]
+      # @param name [Symbol, nil]
+      # @param opts [Hash]
+      # @param scope [Scope] see {Scope} - defaults to {Scope::TOP_LEVEL}
+      # @return [Node]
+      # @raise [ArgumentError] if +name+ is already registered within +scope+
+      def create(type:, name: nil, opts: {}, scope: Scope::TOP_LEVEL)
+        node = Node.new(type: type, name: name, key: generate_key(name), opts: opts, scope: scope, document: self)
+        register(scope, node) if name
+        node
+      end
+
+      # @param name [Symbol]
+      # @param scope [Scope] must be the same {Scope} instance the node
+      #   was {#create}d with - a name registered inside a scope is never
+      #   found by a lookup in a different one, or vice versa
+      # @return [Node, nil]
+      def find(name, scope: Scope::TOP_LEVEL)
+        @index[[scope, name]]
+      end
+      alias_method :[], :find
+
+      # Depth-first, pre-order traversal of the whole tree from {#root}.
+      # @yieldparam node [Node]
+      # @return [Enumerator] if no block given
+      def each_node(&block)
+        root.each(&block)
+      end
+
+      # Every named node, regardless of whether it's actually attached
+      # anywhere in the tree - see {Validator}'s orphan check, which is
+      # exactly the reason this differs from {#each_node}.
+      # @yieldparam name [Symbol]
+      # @yieldparam node [Node]
+      # @return [Enumerator] if no block given
+      def each_named_node(&block)
+        return enum_for(:each_named_node) unless block
+
+        @index.each(&block)
+      end
+
+      # Reverse lookup: given a real Tk path (from an error message, a
+      # +winfo+ query, or poking around in a REPL), find which node it
+      # belongs to - the counterpart to {#find}'s name-based lookup. Only
+      # ever matches a node's own {RealizedNode#path}, never its
+      # +arrange_path+ (the scrollbar-wrapper case - the wrapper frame
+      # itself has no owning node of its own to return) or a
+      # {WidgetType#addressing} strategy's synthesized virtual path (a
+      # menu entry has no real Tk path at all - see
+      # {MenuEntryAddressing#virtual_path}'s own +!+-marked format, never
+      # something Tk itself would hand back from +winfo+ or an error).
+      # @param path [String] a real Tk widget path, e.g. +".toolbar.save"+
+      # @return [Node, nil]
+      def find_by_path(path)
+        each_node.find { |node| node.realized&.path == path }
+      end
+
+      # @api private - called by {Realizer#allocate_path}, which gets a
+      # fresh instance for every separate realize pass (the initial
+      # realize, each {Session#add}, each lazily-{Handle#realize!}d
+      # screen) - tracking claims here instead keeps them honest across
+      # every one of those passes for this Document's whole lifetime.
+      # Two mounts of the same component requesting the same key under
+      # the same real parent (e.g. a reusable row/screen, realized more
+      # than once - see {WidgetDSL#component}) get distinct, disambiguated
+      # segments; the common, non-colliding case keeps its plain segment
+      # unchanged.
+      # @param parent_path [String]
+      # @param segment [String] the requested (not yet disambiguated) segment
+      # @return [String] +segment+, or +segment+ suffixed to make it unique
+      #   under +parent_path+ if this is a repeat
+      def claim_path_segment(parent_path, segment)
+        seen = (@used_segments[parent_path] ||= Hash.new(0))
+        count = seen[segment]
+        seen[segment] += 1
+        count.zero? ? segment : "#{segment}##{count + 1}"
+      end
+
+      # Removes +node+ from the name index, scoped exactly like
+      # {#register} does - a no-op if +node+ was never named (nothing to
+      # remove) or already unregistered. Called by {Handle#destroy!} for
+      # a destroyed node and every named descendant of its own subtree
+      # (Tk destroys descendants recursively, so their names need to
+      # stop resolving too), so a later widget can reuse the same name
+      # in the same scope, and {#find} correctly reports the name as
+      # gone in the meantime.
+      # @param node [Node]
+      # @return [void]
+      def unregister(node)
+        return unless node.name
+
+        @index.delete([node.scope, node.name])
+      end
+
+      private
+
+      def register(scope, node)
+        key = [scope, node.name]
+        if @index.key?(key)
+          suffix = scope.top_level? ? '' : ' in the same component'
+          raise ArgumentError, "duplicate widget name :#{node.name} - already used by a #{@index[key].type} node#{suffix}"
+        end
+
+        @index[key] = node
+      end
+
+      def generate_key(name)
+        return name.to_s if name
+
+        @next_auto_key += 1
+        "#anon#{@next_auto_key}"
+      end
+    end
+  end
+end

data/lib/teek/ui/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    # Raised by any genuinely realize-only method (Session#app, dialogs,
+    # #clipboard, Handle#path/#configure/#modal/#grab_release, ...) called
+    # before its node/session has been realized. These don't queue for
+    # later - the whole point of a Tk-free build phase is that nothing is
+    # pretending to talk to an interpreter that doesn't exist yet, and
+    # each of these either IS the live app/widget by definition or needs
+    # one to do anything meaningful (grabbing input, popping a native
+    # dialog). In practice this is rarely hit in real code: all of them
+    # are normally called from inside an on_* event handler, which only
+    # ever runs after realize - see {Session#every}/{Session#after} for
+    # the one case that genuinely IS deferrable, and queues instead.
+    class NotRealizedError < StandardError
+      def initialize(msg = "not realized yet - call this from an on_* event handler (already " \
+                            "post-realize), or after #run/#run_async/#realize")
+        super
+      end
+    end
+
+    # Raised by {Validator#validate!} when the build tree has one or more
+    # raise-level problems. The message lists every one found, not just the
+    # first, so a build can be fixed in one pass instead of a cycle of
+    # "run, hit the next cryptic Tcl error, fix, repeat."
+    class ValidationError < StandardError; end
+
+    # Raised when a DSL build method (`ui.button`, `ui.panel`, `ui.raw`,
+    # `ui.var`, ...) is called after the build has already realized - the
+    # tree is only ever walked into Tk once, at realize, so anything
+    # appended to it afterward would just silently never show up. Use
+    # {Session#add} instead, which builds and realizes a subtree into the
+    # already-running app immediately.
+    class ClosedBuilderError < StandardError
+      def initialize(msg = "the build has already realized - use session.add(parent_name) { } to add widgets to an already-running app instead")
+        super
+      end
+    end
+  end
+end

data/lib/teek/ui/event_binding.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    # An event a node wants wired up. +target+ is +nil+ to bind on the
+    # node's own widget, or a Symbol naming another node's widget - resolved
+    # by the realizer's link pass, after every node in the whole tree has
+    # already been created, so a target declared later in the build still
+    # resolves correctly (the forward-reference case). +subs+ are
+    # {Teek::App#bind} substitution codes (e.g. +%i[x y]+) forwarded to the
+    # handler when it fires.
+    EventBinding = Data.define(:event, :handler, :target, :subs) do
+      # @param event [String] a Tk bind event pattern, e.g. +"<Button-1>"+
+      # @param handler [#call] called with whatever +subs+ substitutes
+      # @param target [Symbol, nil] another node's name, or nil for self
+      # @param subs [Array<Symbol, String>] see {Teek::App#bind}
+      def initialize(event:, handler:, target: nil, subs: [])
+        super
+      end
+    end
+  end
+end

data/lib/teek/ui/event_bus.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    # In-process publish/subscribe for decoupled app events (+:item_selected+,
+    # +:theme_changed+) - not Tk events, complementary to
+    # {Handle#on_click}/{Handle#on_key}. Reach for this only when a direct
+    # handle or a shared reactive {Var} would couple things that should
+    # stay decoupled.
+    #
+    # Owned by one {Session} (+ui.on+/+ui.emit+/+ui.off+) - two separate
+    # {Teek::UI.app} instances in the same process never share a bus. Pure
+    # Ruby, no Tk/interpreter involved, so it works before realize too.
+    class EventBus
+      # @api private
+      def initialize
+        @listeners = Hash.new { |h, k| h[k] = [] }
+      end
+
+      # Subscribe to a named event.
+      # @param event [Symbol]
+      # @yield the subscriber, called with whatever {#emit} was given
+      # @return [Proc] the block, to pass to a later {#off}
+      def on(event, &block)
+        @listeners[event] << block
+        block
+      end
+
+      # Emit a named event to every current subscriber, in subscription order.
+      # @param event [Symbol]
+      # @param args [Array] forwarded to each subscriber
+      # @param kwargs [Hash] forwarded to each subscriber
+      # @return [void]
+      def emit(event, *args, **kwargs)
+        if kwargs.empty?
+          @listeners[event].each { |listener| listener.call(*args) }
+        else
+          @listeners[event].each { |listener| listener.call(*args, **kwargs) }
+        end
+        nil
+      end
+
+      # Unsubscribe a specific listener.
+      # @param event [Symbol]
+      # @param block [Proc] the block {#on} returned
+      # @return [void]
+      def off(event, block)
+        @listeners[event].delete(block)
+        nil
+      end
+    end
+  end
+end