teek-ui 0.1.0

data/lib/teek/ui/image.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Teek
+  module UI
+    # A DSL-declared image, backed by teek core's {Teek::Photo} (which
+    # owns the underlying Tk image's GC lifetime - see its own docs).
+    #
+    # Declared via {WidgetDSL#image} at build time - its Tcl image name
+    # is allocated purely in Ruby, no interpreter needed yet (same shape
+    # as {Var}'s own Tcl variable name), so it can be captured as a
+    # widget's `image:` option (or a later `handle.configure(image: ...)`
+    # value) before realize even happens. The real {Teek::Photo} - and
+    # the actual file load - only exists at #realize.
+    #
+    # #to_s returns the Tcl name (matching {Teek::Photo}'s own
+    # convention), so passing an Image directly as an `image:` option
+    # value works through teek's ordinary option-value serialization -
+    # no special-casing needed anywhere in the widget DSL for it.
+    class Image
+      # @return [String] the Tcl image name
+      attr_reader :name
+
+      # @api private
+      def initialize(name, path, opts)
+        @name = name
+        @path = path
+        @opts = opts
+        @photo = nil
+      end
+
+      # @return [Teek::Photo] the live, GC-owned Tk photo image, loaded
+      #   from the file path this was declared with
+      # @raise [NotRealizedError] before realize
+      def photo
+        @photo or raise NotRealizedError
+      end
+
+      # Loads the backing {Teek::Photo} from this image's file path.
+      # Called once by {Session#realize}, before the widget tree
+      # realizes, so any widget's `image:` option already resolves to a
+      # real, loaded image by the time it's created.
+      # @api private
+      def realize(app)
+        @photo = Teek::Photo.new(app, name: @name, file: @path, **@opts)
+      end
+
+      # @return [String] the Tcl image name - lets this be passed
+      #   directly as a widget's `image:` option, at build time or via a
+      #   later `handle.configure(image: ...)`, the same way
+      #   {Teek::Photo} itself already can be.
+      def to_s
+        @name
+      end
+    end
+  end
+end

data/lib/teek/ui/keysyms.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    # Translates the DSL's Tk-free key vocabulary (friendly symbols, "Ctrl-x"
+    # style modifier strings) into real Tk bind event patterns. Its own small
+    # lookup, kept separate from Handle so it's easy to extend.
+    module Keysyms
+      # Friendly name -> Tk keysym. Anything not listed here passes through
+      # as the literal keysym (so e.g. :q or "q" still works for plain letter
+      # keys without needing an entry).
+      FRIENDLY = {
+        enter: 'Return', return: 'Return', escape: 'Escape', tab: 'Tab',
+        space: 'space', backspace: 'BackSpace', delete: 'Delete', insert: 'Insert',
+        up: 'Up', down: 'Down', left: 'Left', right: 'Right',
+        home: 'Home', end: 'End', page_up: 'Prior', page_down: 'Next',
+      }.merge((1..12).to_h { |n| [:"f#{n}", "F#{n}"] }).freeze
+
+      # "Ctrl"/"Cmd"/etc, however people spell them -> Tk's own modifier keyword.
+      MODIFIER_ALIASES = {
+        'ctrl' => 'Control', 'control' => 'Control',
+        'alt' => 'Alt', 'option' => 'Alt', 'opt' => 'Alt',
+        'shift' => 'Shift',
+        'cmd' => 'Command', 'command' => 'Command', 'meta' => 'Meta',
+      }.freeze
+
+      # @param spec [Symbol, String] a friendly key (+:enter+) or a
+      #   "Modifier-Modifier-Key" string (+"Ctrl-Shift-s"+)
+      # @return [Array(Array<String>, String)] [tk_modifiers, tk_keysym]
+      def self.resolve(spec)
+        return [[], FRIENDLY.fetch(spec) { spec.to_s }] if spec.is_a?(Symbol)
+
+        parts = spec.to_s.split('-')
+        base = parts.pop
+        keysym = FRIENDLY.fetch(base.downcase.to_sym) { base }
+        modifiers = parts.map { |part| MODIFIER_ALIASES.fetch(part.downcase, part) }
+        [modifiers, keysym]
+      end
+
+      # Tk event patterns to bind for a resolved [modifiers, keysym] pair -
+      # usually just one, but Shift+Tab is a known cross-platform gotcha:
+      # X11 delivers it as the distinct keysym ISO_Left_Tab, not Tab with a
+      # Shift modifier, so binding only <Shift-Tab> silently never fires
+      # there. Bind every spelling so the handler fires regardless of
+      # platform; on platforms where a given spelling never occurs, that
+      # binding is simply inert.
+      # @param modifiers [Array<String>]
+      # @param keysym [String]
+      # @return [Array<String>] Tk bind event patterns, e.g. +["<Control-s>"]+
+      def self.patterns_for(modifiers, keysym)
+        if keysym == 'Tab' && modifiers.include?('Shift')
+          without_shift = modifiers - ['Shift']
+          [
+            pattern(modifiers, 'Tab'),
+            pattern(without_shift, 'ISO_Left_Tab'),
+            pattern(modifiers, 'ISO_Left_Tab'),
+          ].uniq
+        else
+          [pattern(modifiers, keysym)]
+        end
+      end
+
+      class << self
+        private
+
+        def pattern(modifiers, keysym)
+          "<#{(modifiers + [keysym]).join('-')}>"
+        end
+      end
+    end
+  end
+end

data/lib/teek/ui/menu_builder.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative 'handle'
+
+module Teek
+  module UI
+    # The build surface inside a `menu_bar`/`menu`/`context_menu` block - a
+    # separate, small vocabulary from {WidgetDSL} (deliberately NOT mixed
+    # into {Session}/yielded as `self` the way ordinary containers are),
+    # since menu entries reuse names ordinary widgets already own
+    # (`checkbox`/`radio` are ttk widgets one level up, menu entry kinds one
+    # level down here) - a shared receiver would collide.
+    #
+    # Menu structure realizes through {Realizer#create_menu_tree} rather
+    # than the generic per-node widget-creation path: nothing here is a Tk
+    # widget of its own except `#menu` (a nested cascade, itself a `menu`
+    # command) - `#item`/`#checkbox`/`#radio` are entries added to their
+    # parent's menu path, with no live Tk path of their own, addressed via
+    # their {WidgetType#addressing} strategy ({MenuEntryAddressing}) the
+    # same way {Handle} resolves any other type's - see
+    # {WidgetDSL#[]}. `#separator` stays unaddressable (nothing to
+    # enable/disable/relabel on a divider).
+    class MenuBuilder
+      # @api private
+      def initialize(document, stack)
+        @document = document
+        @stack = stack
+      end
+
+      # A nested cascade - recursive, so the same method builds both a
+      # menu_bar's top-level dropdowns (File/Edit/...) and any submenu
+      # nested inside one of those.
+      # @param name [Symbol, nil]
+      # @param label [String] the cascade's displayed label
+      # @param opts [Hash] extra Tk menu-entry options (e.g. +underline:+)
+      # @yieldparam m [MenuBuilder] this same builder, scoped to the new menu
+      # @return [Handle]
+      def menu(name = nil, label:, **opts, &block)
+        node = @document.create(type: :menu, name: name, opts: opts.merge(label: label))
+        @stack.last.add_child(node)
+
+        if block
+          @stack.push(node)
+          @document.notify(:push, node, current_path)
+          begin
+            block.call(self)
+          ensure
+            path = current_path
+            @stack.pop
+            @document.notify(:pop, node, path)
+          end
+        end
+
+        Handle.new(node)
+      end
+
+      # A command entry.
+      # @param name [Symbol, nil] for `ui[:name]` lookup - addressable
+      #   later as a Handle (`.enable`/`.disable`/`.configure`)
+      # @param label [String]
+      # @param opts [Hash] extra Tk menu-entry options (e.g. +accelerator:+)
+      # @yield called when the entry is invoked
+      # @return [Handle]
+      def item(name = nil, label:, **opts, &block)
+        opts = opts.merge(command: block) if block
+        Handle.new(append_entry(:menu_item, name, opts.merge(label: label)))
+      end
+
+      # A separator entry.
+      # @return [nil]
+      def separator
+        append_entry(:menu_separator, nil, {})
+        nil
+      end
+
+      # A checkbutton entry, bound to a reactive {Var} - ticked when the
+      # var is true, unticked when false, the same +bind:+ convention
+      # {WidgetDSL}'s own `checkbox` widget uses.
+      # @param name [Symbol, nil] see {#item}
+      # @param label [String]
+      # @param bind [Var]
+      # @param opts [Hash] extra Tk menu-entry options
+      # @return [Handle]
+      def checkbox(name = nil, label:, bind:, **opts)
+        Handle.new(append_entry(:menu_checkbox, name, opts.merge(label: label, bind: bind)))
+      end
+
+      # A radiobutton entry - `bind:` is shared across every radio entry in
+      # the group, `value:` is what this one entry sets it to when chosen.
+      # @param name [Symbol, nil] see {#item}
+      # @param label [String]
+      # @param bind [Var]
+      # @param value [Object]
+      # @param opts [Hash] extra Tk menu-entry options
+      # @return [Handle]
+      def radio(name = nil, label:, bind:, value:, **opts)
+        Handle.new(append_entry(:menu_radio, name, opts.merge(label: label, bind: bind, value: value)))
+      end
+
+      private
+
+      def append_entry(type, name, opts)
+        node = @document.create(type: type, name: name, opts: normalize_shortcut(opts))
+        @stack.last.add_child(node)
+        node
+      end
+
+      # +shortcut:+ is the friendly primary for Tk's own +accelerator:+
+      # menu-entry option - purely the text displayed next to the label
+      # (e.g. +"Ctrl+S"+), not an actual key binding; see the README's
+      # own note on wiring the real keystroke separately.
+      def normalize_shortcut(opts)
+        return opts unless opts.key?(:shortcut)
+
+        opts = opts.dup
+        opts[:accelerator] = opts.delete(:shortcut)
+        opts
+      end
+
+      # Same computation as {WidgetDSL#current_path} (not the SAME public
+      # method - a separate, small builder with no access to it) - just
+      # enough to give a +:push+/+:pop+ notification its own ancestry
+      # breadcrumb, matching what {WidgetDSL#push_stack}/{#pop_stack}
+      # already do for every other container.
+      def current_path
+        @stack.reject { |node| node.type == :root }.map(&:display_name).join(' > ')
+      end
+    end
+  end
+end

data/lib/teek/ui/menu_entry_addressing.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'option_dump_parsing'
+
+module Teek
+  module UI
+    # @api private
+    #
+    # The {WidgetType#addressing} strategy for :menu_item/:menu_checkbox/
+    # :menu_radio - a menu entry has no independent Tk path of its own,
+    # only the enclosing menu does. #configure resolves the entry's
+    # CURRENT position fresh on every call via {Node#parent} rather than
+    # caching an index, so an earlier sibling being inserted or removed
+    # can never leave this addressing the wrong entry (Tk menu entries
+    # are addressed purely by numeric index, and TkMenu.c renumbers every
+    # entry after the one that changed).
+    class MenuEntryAddressing
+      # @api private
+      def initialize(node)
+        @node = node
+      end
+
+      # @return [String] the parent menu's real path, marked past the
+      #   point a real Tk path stops applying - +!+ 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.
+      def virtual_path
+        "#{menu.path}!#{@node.name || @node.key}"
+      end
+
+      # @param opts [Hash]
+      # @return [void]
+      # @raise [NotRealizedError] before the parent menu is realized
+      def configure(**opts)
+        menu.app.command(menu.path, :entryconfigure, current_index, **opts)
+      end
+
+      # @return [Hash{Symbol => String}] every current option/value Tk
+      #   reports for this entry right now
+      # @raise [NotRealizedError] before the parent menu is realized
+      def option_dump
+        OptionDumpParsing.parse(menu.app, menu.app.command(menu.path, :entryconfigure, current_index))
+      end
+
+      private
+
+      def menu
+        @node.parent&.realized or raise NotRealizedError
+      end
+
+      # The Document tree's own child order exactly matches the live
+      # menu's entry order - {Realizer#create_menu_tree} adds every
+      # child, in order, with one Tk `add` call each - so no live re-scan
+      # of the menu is needed to find this entry's current position.
+      def current_index
+        @node.parent.children.index(@node)
+      end
+    end
+  end
+end

data/lib/teek/ui/modal_stack.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative 'screens'
+
+module Teek
+  module UI
+    # Push/pop stack for modal window handles, so one modal can push
+    # another (e.g. Settings -> Replay Player) with the previous modal
+    # automatically re-shown once the new one is dismissed.
+    #
+    # The reveal/conceal-on-transition bookkeeping - including on-demand
+    # {Handle#realize!} of a not-yet-realized `lazy: true` modal, given
+    # `document:` (a "child window" opened fresh each time, say) - is
+    # exactly what {Screens} already does, so this wraps one internally
+    # rather than re-deriving it. What's actually different here is the
+    # on_enter/on_exit/on_focus_change lifecycle, useful for pause/resume-
+    # style hooks (e.g. pausing an emulator while any modal is open). Each
+    # window handle pushed here should typically be declared `modal: true`
+    # (as `ui.dialog` already defaults to) for `Handle#show` to actually
+    # grab input - ModalStack itself does no grabbing of its own.
+    #
+    # @example
+    #   ui.modal = Teek::UI::ModalStack.new(
+    #     on_enter: ->(name) { pause_emulation },
+    #     on_exit: -> { unpause_emulation },
+    #     on_focus_change: ->(name) { update_toast(name) },
+    #   )
+    #   ui.modal.push(:settings, ui[:settings])
+    #   ui.modal.push(:replay, ui[:replay])   # settings auto-withdrawn
+    #   ui.modal.pop                          # replay closed, settings re-shown
+    #   ui.modal.pop                          # settings closed, on_exit fires
+    class ModalStack
+      # @param on_enter [Proc] called with (name) when the stack goes empty -> non-empty
+      # @param on_exit [Proc] called with no arguments when the stack goes non-empty -> empty
+      # @param on_focus_change [Proc, nil] called with (name) whenever the top modal changes -
+      #   every push, and every pop that leaves a modal underneath (not the final pop, which
+      #   fires on_exit instead)
+      # @param document [Document, nil] forwarded to the internal {Screens}
+      #   - see {Screens#initialize} - needed only to lazily {Handle#realize!}
+      #   a not-yet-realized modal on push
+      def initialize(on_enter:, on_exit:, on_focus_change: nil, document: nil)
+        @screens = Screens.new(document: document)
+        @on_enter = on_enter
+        @on_exit = on_exit
+        @on_focus_change = on_focus_change
+      end
+
+      # @return [Boolean] true if any modal is open
+      def active?
+        @screens.active?
+      end
+
+      # @return [Symbol, nil] name of the topmost modal
+      def current
+        @screens.current
+      end
+
+      # @return [Integer] number of modals on the stack
+      def size
+        @screens.size
+      end
+
+      # Push a modal window handle onto the stack. Whatever was on top (if
+      # any) is withdrawn first, with no callback of its own - it's
+      # stepping aside, not being dismissed. `on_enter` fires only if the
+      # stack was empty; `on_focus_change` fires unconditionally.
+      # @param name [Symbol]
+      # @param window [Handle] a `:window` handle
+      # @return [void]
+      def push(name, window)
+        was_empty = !@screens.active?
+
+        @screens.push(name, window)
+
+        @on_enter.call(name) if was_empty
+        @on_focus_change&.call(name)
+        nil
+      end
+
+      # Pop the current modal off the stack. If a modal remains
+      # underneath, it's re-shown (by {Screens#pop}) and `on_focus_change`
+      # fires for it; otherwise the stack is now empty and `on_exit` fires
+      # instead.
+      # @return [Object, nil] the just-popped window, or +nil+ if the stack was empty
+      def pop
+        return nil unless @screens.active?
+
+        popped = @screens.pop
+
+        if @screens.active?
+          @on_focus_change&.call(@screens.current)
+        else
+          @on_exit.call
+        end
+        popped
+      end
+    end
+  end
+end

data/lib/teek/ui/mouse_events.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'teek/platform'
+
+module Teek
+  module UI
+    # @api private
+    #
+    # Shared mouse-event vocabulary between {Handle} and {CanvasItem}'s own
+    # +on_right_click+, so both mean exactly the same "right click, however
+    # the platform spells it" and "these are the two things you're allowed
+    # to pop up."
+    module MouseEvents
+      # A right click, however the platform spells it - the real right
+      # mouse button everywhere (+<Button-3>+), plus macOS's two long-
+      # standing secondary-click gestures (+<Button-2>+, and
+      # +<Control-Button-1>+ from the one-button-mouse era) - NOT bound on
+      # other platforms, where Ctrl+click carries no such meaning (and on
+      # X11 specifically, Button-2 is the middle mouse button, a real,
+      # distinct button of its own) - binding them unconditionally there
+      # would silently fire a "right click" handler on gestures users
+      # never intended as one.
+      RIGHT_CLICK_EVENTS = (
+        Teek.platform.darwin? ? %w[<Button-2> <Button-3> <Control-Button-1>] : %w[<Button-3>]
+      ).freeze
+
+      # Handle types +on_right_click(menu)+ accepts to pop up.
+      MENU_HANDLE_TYPES = %i[menu context_menu].freeze
+    end
+  end
+end

data/lib/teek/ui/node.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative 'scope'
+
+module Teek
+  module UI
+    # A single element of the retained-mode tree - a widget, layout
+    # container, reactive var, or deferred build-time op (the categories
+    # from the architecture doc; this class itself is generic across all of
+    # them). Plain Ruby, no Tk: constructible, mutable, and traversable with
+    # no interpreter, which is what makes the tree headless-testable.
+    #
+    # +key+ is this node's stable identity - the explicit +name+ if given,
+    # else whatever the owning {Document} assigns. +realized+ stays nil for
+    # the whole build phase; a realizer fills it in later with a live
+    # handle.
+    class Node
+      attr_reader :type, :name, :opts, :children, :events, :parent, :scope, :document
+      attr_accessor :key, :layout, :realized
+      attr_writer :lazy, :pending_destroy
+
+      # @param type [Symbol] node kind, e.g. +:button+, +:column+, +:var+
+      # @param name [Symbol, nil] explicit stable name, for addressing (+ui[:name]+)
+      # @param key [String, nil] stable identity; defaults to +name+'s string form
+      # @param opts [Hash] widget/node options as plain Ruby values
+      # @param scope [Scope] the component scope this node was built in -
+      #   {Scope::TOP_LEVEL} (the default) for a build that never calls
+      #   {WidgetDSL#component}
+      # @param document [Document, nil] back-reference to the owning
+      #   {Document} - set by {Document#create}; +nil+ for a raw +Node.new+
+      #   built directly (headless tests, mostly). Lets {Handle#destroy!}
+      #   unregister a destroyed node's own name(s) without every caller
+      #   needing to thread a Document reference through by hand.
+      def initialize(type:, name: nil, key: nil, opts: {}, scope: Scope::TOP_LEVEL, document: nil)
+        @type = type
+        @name = name
+        @key = key || name&.to_s
+        @opts = opts
+        @children = []
+        @layout = nil
+        @events = []
+        @realized = nil
+        @parent = nil
+        @scope = scope
+        @document = document
+        @lazy = false
+        @pending_destroy = false
+      end
+
+      # @return [Boolean] whether this node is excluded from the ambient
+      #   +create+/+link+ tree walk ({Realizer#realize}, {Realizer#realize_subtree})
+      #   - true only for a container built with +lazy: true+ (see
+      #   {WidgetDSL#append_container}). A lazy node stays a normal,
+      #   attached member of the retained tree; it just never gets a real
+      #   Tk widget until something explicitly realizes it (see
+      #   {Handle#realize!}).
+      def lazy?
+        @lazy
+      end
+
+      # @return [Boolean] whether a deferred {Handle#destroy!} is
+      #   currently scheduled (via +after idle+) but hasn't run yet -
+      #   lets a second +destroy!+ call on the same still-pending handle
+      #   no-op instead of double-scheduling.
+      def pending_destroy?
+        @pending_destroy
+      end
+
+      # @param node [Node]
+      # @return [Node] the node just added
+      def add_child(node)
+        @children << node
+        node.parent = self
+        document&.notify(:append, self, node)
+        node
+      end
+
+      # A short, human label for this node - its type, plus the explicit
+      # name if it has one (e.g. +"column"+ or +"column(:ctrl)"+). Used by
+      # {TreeInspector} and the build stack's own +current_path+ breadcrumb
+      # ({WidgetDSL#current_path}) - deliberately bare (no leading marker,
+      # no "unnamed" filler text) since both of those read as a sequence
+      # of these, not a single prose sentence the way {Realizer}'s own
+      # private +describe+ does.
+      # @return [String]
+      def display_name
+        name ? "#{type}(:#{name})" : type.to_s
+      end
+
+      # Unlinks +node+ from this node's own children - the symmetric
+      # counterpart to {#add_child}, used by {Handle#destroy!} so a
+      # destroyed node stops being reachable from the retained tree at
+      # all (not just Tk-dead - actually gone from +children+, so a
+      # later sibling addition never iterates it, and it becomes
+      # collectable once nothing else references it).
+      # @param node [Node]
+      # @return [Node] the node just removed
+      def remove_child(node)
+        @children.delete(node)
+        node.parent = nil
+        node
+      end
+
+      # Depth-first, pre-order traversal of this node and its descendants.
+      # @yieldparam node [Node]
+      # @return [Enumerator] if no block given
+      def each(&block)
+        return enum_for(:each) unless block
+
+        block.call(self)
+        children.each { |child| child.each(&block) }
+      end
+
+      # This node's address, computed purely from the retained tree
+      # (name/key + {#parent}) - no Tk involved, correct before realize.
+      # For an ordinary widget this already equals the real Tk path
+      # ({Realizer#allocate_path} walks this identical parent/segment
+      # structure); for anything without an independent Tk path of its
+      # own (a menu entry, say), an {Addressing} strategy extends past
+      # this with its own marker rather than pretending it's a real one.
+      # The other documented exception: a reusable component mounted more
+      # than once under the same real parent - {Realizer#allocate_path}
+      # only discovers that repeat (and disambiguates the later mounts'
+      # paths) at realize, so this can't predict it ahead of time either.
+      # A node that isn't attached anywhere yet (+parent+ nil, and not
+      # itself the root) is treated as top-level - the best answer
+      # available without a tree to place it in.
+      # @return [String] e.g. +"."+, +".toolbar"+, +".toolbar.save"+
+      def logical_path
+        return '.' if type == :root
+
+        prefix = (parent.nil? || parent.type == :root) ? '.' : "#{parent.logical_path}."
+        "#{prefix}#{name || key}"
+      end
+
+      protected
+
+      attr_writer :parent
+    end
+  end
+end

data/lib/teek/ui/option_dump_parsing.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    # @api private
+    #
+    # Shared by every {WidgetType#addressing} strategy's own +#option_dump+
+    # (see {WidgetAddressing}, {MenuEntryAddressing}) - the raw Tcl command
+    # differs per strategy (+configure+ vs +entryconfigure <index>+), but
+    # both return the exact same nested-list shape, so the parsing itself
+    # lives in one place rather than two copies drifting apart.
+    module OptionDumpParsing
+      # A bare +configure+ (or +entryconfigure <index>+) call returns one
+      # Tcl sublist per option: +{name dbname dbclass default current}+ for
+      # an ordinary option, or a shorter 2-item +{name aliased-name}+ for a
+      # synonym (e.g. +-bg+ pointing at +-background+) - those carry no
+      # value of their own and are skipped.
+      # @param app [Teek::App]
+      # @param raw [String] the unparsed Tcl list +app.command+ returned
+      # @return [Hash{Symbol => String}] option name (no leading +-+) => current value
+      def self.parse(app, raw)
+        app.split_list(raw).each_with_object({}) do |item, dump|
+          parts = app.split_list(item)
+          next if parts.size < 5
+
+          dump[parts[0].sub(/\A-/, '').to_sym] = parts[4]
+        end
+      end
+    end
+  end
+end

data/lib/teek/ui/overlay_anchors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    # @api private
+    #
+    # ui.overlay's at: vocabulary - corners, center, and the four edge
+    # midpoints, spelled in plain English rather than Tk's own compass
+    # anchors (nw/n/ne/w/center/e/sw/s/se) - the same litmus test every
+    # other DSL name follows (decoding one should never need Tk
+    # knowledge). Each maps to `place`'s own -relx/-rely/-anchor, needed
+    # both to validate at: ({WidgetDSL#overlay}) and to actually place the
+    # widget ({Realizer#place_overlay}) - one shared table so the two can
+    # never drift out of sync with each other.
+    module OverlayAnchors
+      POSITIONS = {
+        top_left: { relx: 0.0, rely: 0.0, anchor: 'nw' },
+        top: { relx: 0.5, rely: 0.0, anchor: 'n' },
+        top_right: { relx: 1.0, rely: 0.0, anchor: 'ne' },
+        left: { relx: 0.0, rely: 0.5, anchor: 'w' },
+        center: { relx: 0.5, rely: 0.5, anchor: 'center' },
+        right: { relx: 1.0, rely: 0.5, anchor: 'e' },
+        bottom_left: { relx: 0.0, rely: 1.0, anchor: 'sw' },
+        bottom: { relx: 0.5, rely: 1.0, anchor: 's' },
+        bottom_right: { relx: 1.0, rely: 1.0, anchor: 'se' },
+      }.freeze
+    end
+  end
+end