teek-ui 0.1.0

data/lib/teek/ui/text_content.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    # The rich text API for one +ui.text_area+ widget's content - reached
+    # via {Handle#text_content}, the same shape {Handle#tagged}/{Handle#line}
+    # use to hand back a {CanvasItem}: a small, focused companion object,
+    # not a pile of widget-specific methods on {Handle} itself.
+    #
+    # Indices (every +index+/+from+/+to+/+at+ parameter below) are Tk's own
+    # text index syntax, passed through verbatim as Ruby strings -
+    # +"1.0"+, +"end"+, +"sel.first"+, +"insert +1 line"+, a mark name,
+    # +"@12,34"+ - see the Tk +text+ manual page for the full grammar.
+    # This is deliberately NOT wrapped in a new index type - sugar, not a
+    # wall. Two Symbol shortcuts cover the common cases: +:end+ and
+    # +:cursor+ (the +insert+ mark, renamed to something that doesn't
+    # collide with {#insert} the method).
+    #
+    # Naming: a Tk text "tag" is not an HTML tag - it's a named, reusable
+    # set of display properties you apply to ranges, like a CSS class.
+    # The primary vocabulary here calls that a "format" (avoiding "style",
+    # already taken by ttk's own +style:+ widget option); the Tk-named
+    # methods (+tag_configure+, +tag_add+, ...) still work as plain
+    # aliases, so 1:1 Tk documentation mapping and Tk-fluent muscle memory
+    # both keep working.
+    #
+    # Every content-mutating method (insert/delete/replace/value=/clear/
+    # insert_image) transparently lifts a +-state disabled+ (read-only)
+    # widget to +normal+ for the duration of the call and restores it
+    # after - Tk itself silently no-ops a mutation against a disabled
+    # text widget, which is exactly the kind of Tk wonk this DSL exists
+    # to hide. An app author building a read-only log pane never needs to
+    # know this footgun exists.
+    class TextContent
+      INDEX_ALIASES = { end: 'end', cursor: 'insert' }.freeze
+
+      # @api private
+      def initialize(app, path)
+        @app = app
+        @path = path
+      end
+
+      # -- Content -------------------------------------------------------
+
+      # @param index [String, Symbol]
+      # @param text [String]
+      # @param tags [Array<String, Symbol>] format name(s) to apply to
+      #   the inserted text, same as Tk's own trailing tagList
+      # @return [void]
+      def insert(index, text, *tags)
+        mutate { @app.command(@path, :insert, resolve_index(index), text, *tags) }
+      end
+
+      # @param start [String, Symbol]
+      # @param end_ [String, Symbol, nil] a single character at +start+
+      #   if omitted, the range +[start, end_)+ otherwise
+      # @return [String]
+      def get(start = '1.0', end_ = 'end')
+        @app.command(@path, :get, resolve_index(start), resolve_index(end_))
+      end
+
+      # @param start [String, Symbol]
+      # @param end_ [String, Symbol, nil] a single character at +start+
+      #   if omitted, the range +[start, end_)+ otherwise
+      # @return [void]
+      def delete(start, end_ = nil)
+        mutate { @app.command(@path, :delete, resolve_index(start), *(end_ ? [resolve_index(end_)] : [])) }
+      end
+
+      # Atomic delete-then-insert over +[start, end_)+.
+      # @param start [String, Symbol]
+      # @param end_ [String, Symbol]
+      # @param text [String]
+      # @return [void]
+      def replace(start, end_, text)
+        mutate { @app.command(@path, :replace, resolve_index(start), resolve_index(end_), text) }
+      end
+
+      # @return [String] the whole buffer's text, without the synthetic
+      #   trailing newline Tk always keeps at +end+
+      def value
+        get('1.0', 'end-1c')
+      end
+
+      # Replaces the whole buffer's content outright.
+      # @param text [String]
+      # @return [void]
+      def value=(text)
+        mutate {
+          @app.command(@path, :delete, '1.0', 'end')
+          @app.command(@path, :insert, '1.0', text)
+        }
+      end
+
+      # Empties the whole buffer.
+      # @return [void]
+      def clear
+        mutate { @app.command(@path, :delete, '1.0', 'end') }
+      end
+
+      # -- Formats (Tk's own "tag") ---------------------------------------
+
+      # Defines (or redefines) a named format - a reusable set of display
+      # properties, applied to text ranges via {#apply_format}.
+      # @param name [Symbol, String]
+      # @param opts [Hash] Tk text-tag options, e.g. +foreground:+/+font:+/+underline:+
+      # @return [void]
+      def format(name, **opts)
+        @app.command(@path, :tag, :configure, name, **opts)
+      end
+      alias_method :tag_configure, :format
+
+      # Applies a previously-{#format}ted name to a range.
+      # @param name [Symbol, String]
+      # @param from [String, Symbol]
+      # @param to [String, Symbol]
+      # @return [void]
+      def apply_format(name, from, to)
+        @app.command(@path, :tag, :add, name, resolve_index(from), resolve_index(to))
+      end
+      alias_method :tag_add, :apply_format
+
+      # Removes +name+ from a range - the format definition itself is
+      # untouched, still applyable elsewhere; see {#delete_format} to
+      # remove the definition entirely.
+      # @param name [Symbol, String]
+      # @param from [String, Symbol]
+      # @param to [String, Symbol]
+      # @return [void]
+      def clear_format(name, from, to)
+        @app.command(@path, :tag, :remove, name, resolve_index(from), resolve_index(to))
+      end
+      alias_method :tag_remove, :clear_format
+
+      # Deletes a format's definition entirely, and with it every range
+      # it was applied to.
+      # @param name [Symbol, String]
+      # @return [void]
+      def delete_format(name)
+        @app.command(@path, :tag, :delete, name)
+      end
+      alias_method :tag_delete, :delete_format
+
+      # @param name [Symbol, String]
+      # @return [Array<String>] a flat list of index pairs - +[start1,
+      #   end1, start2, end2, ...]+, one pair per contiguous applied range
+      def format_ranges(name)
+        @app.split_list(@app.command(@path, :tag, :ranges, name))
+      end
+      alias_method :tag_ranges, :format_ranges
+
+      # Fires on a left click anywhere text carrying +name+ is displayed.
+      # Wired through +tag bind+ (not a raw +tcl_eval+), so the existing
+      # leak-safe reconcile (teek core's +TagBindInterceptor+, already
+      # registered for the +text+ widget) releases the callback if +name+
+      # stops being applied anywhere - the same leak-safety every other
+      # DSL event binding already gets.
+      # @param name [Symbol, String]
+      # @yield called with no arguments
+      # @return [void]
+      def on_format_click(name, &block)
+        bind_format_event(name, '<Button-1>', block)
+      end
+      alias_method :on_tag_click, :on_format_click
+
+      # {#on_format_click}, for an arbitrary Tk event pattern instead of
+      # the common left-click case.
+      # @param name [Symbol, String]
+      # @param event [String] a Tk bind event pattern, e.g. +"Double-Button-1"+
+      # @yield called with no arguments
+      # @return [void]
+      def on_format(name, event, &block)
+        bind_format_event(name, resolve_event(event), block)
+      end
+      alias_method :on_tag, :on_format
+
+      # -- Markers (Tk's own "mark") ---------------------------------------
+
+      # A marker is a named, floating position in the text that moves
+      # with edits around it - a bookmark, not a range.
+      # @param name [Symbol, String]
+      # @param at [String, Symbol] where to place it
+      # @return [void]
+      def add_marker(name, at:)
+        @app.command(@path, :mark, :set, name, resolve_index(at))
+      end
+      alias_method :mark_set, :add_marker
+
+      # @param name [Symbol, String]
+      # @return [void]
+      def remove_marker(name)
+        @app.command(@path, :mark, :unset, name)
+      end
+      alias_method :mark_unset, :remove_marker
+
+      # @return [Array<String>] every marker currently defined, including
+      #   the built-in +insert+/+current+ ones
+      def markers
+        @app.split_list(@app.command(@path, :mark, :names))
+      end
+      alias_method :mark_names, :markers
+
+      # Which way +name+ drifts when text is inserted exactly at it -
+      # an advanced, rarely-needed Tk concept, so this stays under its Tk
+      # name only (no friendlier alias).
+      # @param name [Symbol, String]
+      # @param direction [String, Symbol, nil] +:left+/+:right+ to set;
+      #   omit to just read the current gravity
+      # @return [String] +"left"+ or +"right"+
+      def mark_gravity(name, direction = nil)
+        if direction
+          @app.command(@path, :mark, :gravity, name, direction)
+        else
+          @app.command(@path, :mark, :gravity, name)
+        end
+      end
+
+      # -- Search ----------------------------------------------------------
+
+      # @param pattern [String]
+      # @param from [String, Symbol] where to start searching
+      # @param to [String, Symbol] the search boundary - with
+      #   +backwards: true+ this is the earliest index the search may
+      #   reach, same as plain Tk +search+
+      # @param backwards [Boolean]
+      # @param regexp [Boolean] treat +pattern+ as a regular expression
+      # @param nocase [Boolean]
+      # @return [String, nil] the matching index, or +nil+ if not found
+      def search(pattern, from: 'insert', to: 'end', backwards: false, regexp: false, nocase: false)
+        args = []
+        args << '-backward' if backwards
+        args << '-regexp' if regexp
+        args << '-nocase' if nocase
+        args << '--'
+        result = @app.command(@path, :search, *args, pattern, resolve_index(from), resolve_index(to))
+        result.empty? ? nil : result
+      end
+
+      # -- View / cursor / state --------------------------------------------
+
+      # Scrolls the view so +index+ is visible.
+      # @param index [String, Symbol]
+      # @return [void]
+      def scroll_to(index)
+        @app.command(@path, :see, resolve_index(index))
+      end
+      alias_method :see, :scroll_to
+
+      # Resolves any index expression to its canonical +"line.char"+ form.
+      # @param spec [String, Symbol]
+      # @return [String]
+      def index(spec)
+        @app.command(@path, :index, resolve_index(spec))
+      end
+
+      # @return [String] the text cursor's current position (the +insert+
+      #   mark), as +"line.char"+
+      def cursor
+        index('insert')
+      end
+
+      # Moves the text cursor.
+      # @param spec [String, Symbol]
+      # @return [void]
+      def cursor=(spec)
+        add_marker('insert', at: spec)
+      end
+
+      # @return [Boolean] whether this widget currently rejects direct
+      #   typing/edits (its Tk +-state+ is +disabled+) - {#insert}/
+      #   {#delete}/etc still work regardless, temporarily lifting this
+      #   for their own duration (see the class docs)
+      def read_only
+        @app.command(@path, :cget, '-state') == 'disabled'
+      end
+
+      # @param value [Boolean]
+      # @return [void]
+      def read_only=(value)
+        @app.command(@path, :configure, state: value ? :disabled : :normal)
+      end
+
+      # -- Embedded images ---------------------------------------------------
+
+      # Embeds an image inline in the text flow at +index+.
+      # @param index [String, Symbol]
+      # @param image [Image, Teek::Photo] anything whose +#to_s+ is a Tcl
+      #   image name - a DSL {Image} or a raw {Teek::Photo} both work
+      # @return [void]
+      def insert_image(index, image:)
+        mutate { @app.command(@path, :image, :create, resolve_index(index), image: image) }
+      end
+      alias_method :image_create, :insert_image
+
+      private
+
+      def resolve_index(spec)
+        INDEX_ALIASES.fetch(spec, spec).to_s
+      end
+
+      def resolve_event(event)
+        event.start_with?('<') ? event : "<#{event}>"
+      end
+
+      def bind_format_event(name, event, handler)
+        @app.command(@path, :tag, :bind, name, event, proc { |*args| handler.call(*args) })
+      end
+
+      # See the class docs - every content-mutating method routes through
+      # here so a read-only (+-state disabled+) widget never silently
+      # swallows the mutation.
+      def mutate
+        was_read_only = read_only
+        self.read_only = false if was_read_only
+        yield
+      ensure
+        self.read_only = true if was_read_only
+      end
+    end
+  end
+end

data/lib/teek/ui/tree_inspector.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    # Build-phase debug tooling: a readable ASCII tree of a {Document}'s
+    # current shape, and (opt-in) a step-by-step trace of how it got there.
+    # Deliberately its own class, not methods on {Document}/{Node} - those
+    # stay focused on constructing/indexing/parent-tracking the retained
+    # tree; this is purely an outside observer of it, built the same way an
+    # app author's own tooling would be (see {Document#subscribe}).
+    class TreeInspector
+      # One recorded moment of tree assembly - see {#log}.
+      # @!attribute action
+      #   @return [Symbol] +:push+/+:pop+ (the build stack, see
+      #     {WidgetDSL#current_path}) or +:append+ (a node added via
+      #     {Node#add_child})
+      # @!attribute node
+      #   @return [Node] the node pushed/popped/appended
+      # @!attribute path
+      #   @return [String] for +:push+/+:pop+, the full ancestry breadcrumb
+      #     this node had while on top of the stack; for +:append+, its new
+      #     parent's own {Node#display_name}
+      Event = Data.define(:action, :node, :path) do
+        def to_s
+          case action
+          when :push then "-> #{path}"
+          when :pop then "<- #{path}"
+          when :append then "+  #{node.display_name} (under #{path})"
+          end
+        end
+      end
+
+      # @param document [Document]
+      # @param trace [Boolean] subscribe to +document+'s own internal
+      #   build-event hook immediately, recording every stack push/pop and
+      #   node append from this point on - see {#log}. +false+ (the
+      #   default) costs nothing beyond this object's own existence:
+      #   +document+ never learns whether a TreeInspector is watching or
+      #   not, on or off.
+      def initialize(document, trace: false)
+        @document = document
+        @log = []
+        subscribe! if trace
+      end
+
+      # A readable ASCII tree of the document's CURRENT shape - type,
+      # name, and (where present) +opts[:text]+/+opts[:label]+, box-drawn
+      # by nesting. Reflects whatever the tree looks like right now; call
+      # it again after more building to see the updated shape.
+      # @return [String]
+      # @example
+      #   root
+      #   └─ column
+      #      ├─ label "Title"
+      #      ├─ row
+      #      │  ├─ button "OK"
+      #      │  └─ button "Cancel"
+      #      └─ label "Footer"
+      def to_s
+        lines = [@document.root.display_name]
+        append_tree_lines(@document.root, '', lines)
+        lines.join("\n")
+      end
+
+      # {#to_s}, straight to stdout.
+      # @return [void]
+      def print_tree
+        puts to_s
+      end
+
+      # @return [Array<Event>] every push/pop/append recorded so far, in
+      #   order - always empty unless constructed with +trace: true+
+      attr_reader :log
+
+      private
+
+      def subscribe!
+        @document.subscribe(:push) { |node, path| @log << Event.new(action: :push, node: node, path: path) }
+        @document.subscribe(:pop) { |node, path| @log << Event.new(action: :pop, node: node, path: path) }
+        @document.subscribe(:append) { |parent, child| @log << Event.new(action: :append, node: child, path: parent.display_name) }
+      end
+
+      def append_tree_lines(node, prefix, lines)
+        node.children.each_with_index do |child, i|
+          last = i == node.children.length - 1
+          lines << "#{prefix}#{last ? '└─ ' : '├─ '}#{tree_label(child)}"
+          append_tree_lines(child, prefix + (last ? '   ' : '│  '), lines)
+        end
+      end
+
+      def tree_label(node)
+        text = node.opts[:text] || node.opts[:label]
+        text ? "#{node.display_name} #{text.to_s.inspect}" : node.display_name
+      end
+    end
+  end
+end

data/lib/teek/ui/validator.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'widget_validators'
+require_relative 'grid_validator'
+require_relative 'tab_validator'
+require_relative 'pane_validator'
+require_relative 'overlay_validator'
+
+module Teek
+  module UI
+    # Walks a {Document} before realize and collects ALL problems, so a
+    # broken build can be fixed in one pass instead of a cycle of "run, hit
+    # the next cryptic Tcl error, fix, repeat." Headless - no interpreter
+    # needed, since it only ever inspects the tree.
+    #
+    # Two severities: problems that are "definitely broken" raise (folded
+    # into one {ValidationError} listing every one found); problems that
+    # are "probably a mistake" warn via +Kernel#warn+ by default, or raise
+    # too under +strict: true+.
+    #
+    # This class runs the checks that span the whole tree or relate
+    # arbitrary nodes to each other (dangling event targets, orphans). A
+    # specific widget/container's own contract (a grid's children all need
+    # cells, a tab's parent must be a ui.tabs, ...) lives in its own
+    # {WidgetValidators}-registered validator instead (see
+    # {GridValidator}/{TabValidator}/{PaneValidator}/{OverlayValidator}), dispatched by node
+    # type the same way {Teek::CommandInterceptors} dispatches by widget
+    # type. One depth-first walk covers both the document-level checks
+    # below and every registered widget validator.
+    #
+    # A {WidgetType} descriptor's own +validator:+ (see {WidgetTypes})
+    # needs no separate handling here at all - {WidgetTypes.register}
+    # forwards it into {WidgetValidators} directly, so it's dispatched
+    # through the exact same +WidgetValidators.for_type+ call every other
+    # validator already goes through.
+    #
+    # @note "Mixed pack+grid geometry in one container" (the classic Tk-hangs
+    #   hazard) isn't checked here because, within the pure DSL layout path,
+    #   it can't happen: {Realizer#arrange_children} picks exactly one
+    #   arrangement strategy per container, from that container's own node
+    #   type, and every container realizes into its own dedicated Tk master
+    #   - a guarantee locked down by a realizer test (test_realizer.rb)
+    #   asserting no master ever receives calls from more than one manager,
+    #   so a future refactor that shares/flattens frames fails a test
+    #   instead of shipping the hazard silently.
+    #
+    #   That guarantee only covers what the DSL itself can construct,
+    #   though - it says nothing about the escape hatch. +ui.raw+,
+    #   +session.app.command+, and a live handle's own +app.command+ calls
+    #   are opaque Procs the tree-walking validator can't see inside, so a
+    #   raw +pack+/+grid+ call from one of those can still target a master
+    #   the DSL already manages - that's the one real, unguardable vector,
+    #   not "direct Node/Document manipulation" (which is what the narrower
+    #   checks in {GridValidator}/{TabValidator}/{PaneValidator} actually
+    #   guard against). If it happens, Tk itself is a synchronous backstop:
+    #   it refuses a second geometry manager on an already-managed master
+    #   with an immediate, clear +Teek::TclError+ ("cannot use geometry
+    #   manager X inside Y") rather than the classic silent hang - but the
+    #   DSL has no way to stop the mistake up front, so avoid mixing raw
+    #   geometry calls onto a DSL-managed master (see the README's escape
+    #   hatch section).
+    class Validator
+      # @param document [Document]
+      # @param strict [Boolean] promote warn-level problems (currently just
+      #   orphans) to raise-level too
+      # @raise [ValidationError]
+      def self.validate!(document, strict: false)
+        new(document, strict: strict).validate!
+      end
+
+      # @api private
+      def initialize(document, strict: false)
+        @document = document
+        @strict = strict
+        @errors = []
+        @warnings = []
+        @reachable = {}
+      end
+
+      # @return [void]
+      def validate!
+        walk(@document.root, nil)
+        check_orphans
+
+        @warnings.each { |message| warn "teek-ui: #{message}" }
+        raise ValidationError, @errors.join("\n") if @errors.any?
+      end
+
+      private
+
+      # The single tree traversal every check below rides along on - marks
+      # each node reachable (for {#check_orphans}), dispatches to every
+      # {WidgetValidators}-registered validator for the node's own type,
+      # and runs {GridValidator#check_stray_cell}/{OverlayValidator#check_stray_overlay}
+      # (see their own comments for why those can't be type-dispatched)
+      # plus the dangling-event-target check, all of which genuinely span
+      # arbitrary node types.
+      def walk(node, parent)
+        @reachable[node] = true
+
+        GridValidator.check_stray_cell(node, parent, @errors)
+        OverlayValidator.check_stray_overlay(node, parent, @errors)
+        WidgetValidators.for_type(node.type).each { |validator| validator.call(node, parent, @document, @errors) }
+        check_dangling_event_targets(node)
+
+        node.children.each { |child| walk(child, node) }
+      end
+
+      def check_dangling_event_targets(node)
+        node.events.each do |binding|
+          next unless binding.target
+          next if @document.find(binding.target, scope: node.scope)
+
+          @errors << "#{WidgetValidators.describe(node)}'s event binding targets :#{binding.target}, " \
+                      "but no widget with that name exists"
+        end
+      end
+
+      def check_orphans
+        @document.each_named_node do |_name, node|
+          next if @reachable[node]
+
+          message = "#{WidgetValidators.describe(node)} is declared but never placed in the layout - " \
+                     "it will exist but never realize/show"
+          @strict ? @errors << message : @warnings << message
+        end
+      end
+    end
+  end
+end

data/lib/teek/ui/var.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Teek
+  module UI
+    # A reactive Tcl variable, wrapped for Ruby - Tk's own native
+    # -textvariable/-variable machinery, done properly instead of the
+    # hand-rolled "VAR_NAME constant + manual set_variable/get_variable"
+    # pattern this replaces. Widgets bound to the same Var stay in sync with
+    # each other for free (that part is entirely Tk's doing); this class
+    # adds typed Ruby access and an on_change callback on top.
+    #
+    # Its Tcl variable name is allocated at build time (see {WidgetDSL#var})
+    # - a plain string, no interpreter needed - so widgets can capture it as
+    # a `-variable`/`-textvariable` option before realize even happens. The
+    # variable itself, its initial value, and its change trace only become
+    # real at #realize.
+    class Var
+      # @return [String] the Tcl variable name
+      attr_reader :name
+
+      # @api private
+      def initialize(name, initial)
+        @name = name
+        @initial = initial
+        @on_change_callbacks = []
+        @app = nil
+      end
+
+      # The current value, coerced to match the initial value's type
+      # (Integer/Float/Boolean pass through typed; anything else is a String).
+      # @raise [NotRealizedError] before realize
+      def value
+        raise_unless_realized!
+        coerce(@app.get_variable(@name))
+      end
+
+      # @raise [NotRealizedError] before realize
+      def value=(new_value)
+        raise_unless_realized!
+        @app.set_variable(@name, to_tcl(new_value))
+      end
+
+      # Register a callback fired whenever the value changes, regardless of
+      # whether Ruby (#value=) or a bound widget caused it. Queues
+      # regardless of build/realize phase - there's only ever one
+      # underlying Tcl trace per Var, wired once at realize, so callbacks
+      # added later just join the same list.
+      # @yield [value] the new, coerced value
+      # @return [self]
+      def on_change(&block)
+        @on_change_callbacks << block
+        self
+      end
+
+      # Create the backing Tcl variable, set its initial value, and wire the
+      # change trace. Called once by {Session#realize}, before the widget
+      # tree realizes, so bound widgets display the initial value from the
+      # moment they're created rather than starting blank.
+      # @api private
+      def realize(app)
+        @app = app
+        @app.set_variable(@name, to_tcl(@initial))
+        cb_id = @app.register_callback(proc { |*| notify_change })
+        @app.tcl_eval("trace add variable #{@name} write {ruby_callback #{cb_id}}")
+      end
+
+      private
+
+      def notify_change
+        current = coerce(@app.get_variable(@name))
+        @on_change_callbacks.each { |callback| callback.call(current) }
+      end
+
+      def to_tcl(v)
+        case v
+        when true then '1'
+        when false then '0'
+        else v.to_s
+        end
+      end
+
+      def coerce(raw)
+        case @initial
+        when Integer then raw.to_i
+        when Float then raw.to_f
+        when true, false then raw == '1'
+        else raw
+        end
+      end
+
+      def raise_unless_realized!
+        raise NotRealizedError unless @app
+      end
+    end
+  end
+end

data/lib/teek/ui/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Teek
+  module UI
+    VERSION = "0.1.0"
+  end
+end