teek-ui 0.1.0

data/lib/teek/ui/widget_type.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative 'widget_addressing'
+
+module Teek
+  module UI
+    # @api private
+    #
+    # A single widget/node type's own metadata: what it draws, how it's
+    # built and arranged, what it validates - self-contained enough that
+    # {WidgetDSL} (the builder), {Realizer}, and {Validator} can each treat
+    # a registered type as the sole source of truth for it, dispatched by
+    # node type via {WidgetTypes}.
+    #
+    # Leaf defaults cover the common case, so a real widget is a ~5-line
+    # descriptor: +WidgetType.new(type: :divider, tk_command:
+    # 'ttk::separator')+ is a complete, working leaf widget. A container,
+    # or a widget needing bespoke DSL methods/realize setup, overrides
+    # +dsl:+/+post_create:+.
+    class WidgetType
+      attr_reader :type, :tk_command, :bind_option, :validator, :flow, :addressing
+
+      # @param type [Symbol] the node type this describes, e.g. +:divider+
+      # @param tk_command [String] the Tk widget-creation command, e.g.
+      #   +'ttk::separator'+ - documentary only for a type that also sets
+      #   +custom_create:+, since that hook bypasses the generic
+      #   widget-creation call this would otherwise drive
+      # @param leaf [Boolean] true for a childless widget (the default);
+      #   false for a container that holds a DSL subtree
+      # @param natively_scrollable [Boolean] whether this widget already
+      #   speaks Tk's -yscrollcommand/-xscrollcommand protocol - see
+      #   {Realizer#auto_scrollable?}, which consults this for a registered type
+      # @param scroll_default [Symbol] which {Teek::UI} global default
+      #   reader this type's own auto-scrollable wrapping falls back to
+      #   when neither the widget's own +scroll:+ nor the session's
+      #   app-wide override says otherwise - +:auto_scroll+ (the default)
+      #   for most natively-scrollable types, +:auto_scroll_canvas+ for
+      #   canvas specifically. Only meaningful alongside
+      #   +natively_scrollable: true+ - see {Realizer#resolve_scroll}.
+      # @param arranged [Boolean] whether a geometry manager (pack/grid)
+      #   should place this node inside its parent - true (the default) for
+      #   almost everything; false for a type placed some other way
+      #   entirely, e.g. a toplevel window (placed by the window manager,
+      #   not its nominal parent) or a tab/pane (placed by its own
+      #   container's `add` command) - see {Realizer#unarranged?}, which
+      #   consults this for a registered type
+      # @param bind_option [Symbol, nil] the Tk option `bind:` plugs a
+      #   {Var} into for this widget (+:textvariable+/+:variable+/...) -
+      #   +nil+ (the default) means this widget doesn't support `bind:`
+      # @param flow [Hash, nil] flow-packing config for a `column`/`row`-
+      #   style container (side/main_pad/cross_pad/main_fill/cross_fill/
+      #   anchor) - +nil+ (the default) means this type isn't flow-arranged.
+      #   A convenience over +arrange:+ for exactly this shape: giving
+      #   +flow:+ computes an +arrange:+ that delegates to
+      #   {Realizer#arrange_flow} with this data, so most flow containers
+      #   never need to touch +arrange:+ directly.
+      # @param arrange [#call, nil] +->(realizer, node, children) { ... }+,
+      #   replaces the realizer's generic "pack every child plainly"
+      #   default arrangement for this type entirely - e.g. real Tk grid
+      #   placement (row/col/span/stretch) for a `:grid`-shaped type. Since
+      #   the logic usually needs realizer-private helpers (gap/align
+      #   computation, error formatting, ...), the callable is typically a
+      #   thin adapter delegating back via +realizer.send(:some_private_method, ...)+
+      #   rather than reimplementing arrangement from scratch - see
+      #   {Realizer#arrange_grid} for an example. +nil+ (the default,
+      #   unless +flow:+ computed one) means the generic pack default applies.
+      # @param custom_children [#call, nil] +->(realizer, node, path) { ... }+,
+      #   replaces the realizer's generic "create every child normally"
+      #   step for this type, once its OWN widget has already been created
+      #   the normal way - e.g. `:scrollable`'s children live inside an
+      #   embedded canvas+viewport it builds itself, not directly under its
+      #   own path. +nil+ (the default) means children realize normally.
+      # @param custom_create [#call, nil] +->(realizer, node, parent_path) { ... }+,
+      #   replaces the realizer's ENTIRE per-node create/link handling for
+      #   this type - no generic widget-creation call, no {#post_create},
+      #   no {#arrange}/`custom_children`, no normal `link` processing
+      #   (events/close-handler/child recursion) either. For a type whose
+      #   realize model doesn't share ANY of that machinery at all - e.g.
+      #   `:menu_bar`/`:context_menu`, realized via
+      #   {Realizer#create_menu_tree}'s own bespoke traversal, using
+      #   `Teek::App#menu` rather than a generic widget-creation command.
+      #   +nil+ (the default) means this type goes through the normal
+      #   create/link two-pass path.
+      # @param validator [#call, nil] a +(node, parent, document, errors)+
+      #   callable checking this type's own contract - a REFERENCE to an
+      #   already-written validator (e.g. an existing WidgetValidators-style
+      #   module), not duplicated logic. Composed into {WidgetValidators}
+      #   automatically at {WidgetTypes.register} time, so {Validator}
+      #   needs no separate awareness of descriptors at all.
+      # @param dsl [Proc, nil] +->(mod) { ... }+, called once at
+      #   {WidgetTypes.register} time (and replayed for any subscriber that
+      #   joins later - see {WidgetTypes.on_register}) to define this
+      #   type's `ui.<type>` method(s) on the builder module. Defaults to
+      #   the leaf/container-appropriate +append_leaf+/+append_container+
+      #   call - pass +->(mod) { }+ (a genuine no-op) for a type reachable
+      #   only via a bespoke, hand-written top-level method with a
+      #   different signature (e.g. `#tab`/`#pane`/`#split`, or
+      #   `#menu_bar`/`#context_menu`), so the registry doesn't shadow it
+      #   with a same-named generic method.
+      # @param post_create [#call, nil] +->(app, node, path, parent_path) { ... }+,
+      #   run right after the generic widget-creation command at realize -
+      #   see {WindowRealize}/{TabRealize}/{PaneRealize} for real examples.
+      #   Defaults to a no-op. Not called at all for a type that sets
+      #   +custom_create:+, since that hook bypasses this entire step.
+      # @param addressing [#new, nil] a class - +->(node) { ... }+-shaped
+      #   via +.new+ - knowing how to read/write THIS type's live state
+      #   (+#virtual_path+, +#configure+). {Handle} resolves this per node
+      #   from the registry, with no type-specific knowledge of its own -
+      #   a plugin/custom widget type gets correct addressing purely by
+      #   registering its own +addressing:+ here. Defaults to
+      #   {WidgetAddressing} (an ordinary Tk widget with its own path) -
+      #   see {MenuEntryAddressing} for a type with none of its own.
+      def initialize(type:, tk_command:, leaf: true, natively_scrollable: false, arranged: true,
+                      scroll_default: :auto_scroll, bind_option: nil, flow: nil, arrange: nil,
+                      custom_children: nil, custom_create: nil, validator: nil, dsl: nil, post_create: nil,
+                      addressing: WidgetAddressing)
+        @type = type.to_sym
+        @tk_command = tk_command
+        @leaf = leaf
+        @natively_scrollable = natively_scrollable
+        @arranged = arranged
+        @scroll_default = scroll_default
+        @bind_option = bind_option
+        @flow = flow
+        @arrange = arrange || (flow && ->(realizer, node, children) { realizer.send(:arrange_flow, node, children, flow) })
+        @custom_children = custom_children
+        @custom_create = custom_create
+        @validator = validator
+        @dsl = dsl || default_dsl
+        @addressing = addressing
+        @post_create = post_create
+      end
+
+      # @return [Boolean]
+      def leaf?
+        @leaf
+      end
+
+      # @return [Boolean]
+      def container?
+        !@leaf
+      end
+
+      # @return [Boolean]
+      def natively_scrollable?
+        @natively_scrollable
+      end
+
+      # @return [Boolean] the current value of this type's own
+      #   {Teek::UI} global scroll-default reader (+scroll_default:+)
+      def global_scroll_default
+        Teek::UI.public_send(@scroll_default)
+      end
+
+      # @return [Boolean]
+      def arranged?
+        @arranged
+      end
+
+      # @return [Boolean] whether this type replaces the generic arrangement
+      def arrange?
+        !@arrange.nil?
+      end
+
+      # Runs this type's custom arrangement strategy.
+      # @param realizer [Realizer]
+      # @param node [Node]
+      # @param children [Array<Node>] this node's arrangeable children
+      # @return [void]
+      def arrange(realizer, node, children)
+        @arrange.call(realizer, node, children)
+      end
+
+      # @return [Boolean] whether this type replaces generic child creation
+      def custom_children?
+        !@custom_children.nil?
+      end
+
+      # Runs this type's custom child-creation strategy, once its own
+      # widget already exists at +path+.
+      # @param realizer [Realizer]
+      # @param node [Node]
+      # @param path [String]
+      # @return [void]
+      def custom_children(realizer, node, path)
+        @custom_children.call(realizer, node, path)
+      end
+
+      # @return [Boolean] whether this type replaces the entire create/link handling
+      def custom_create?
+        !@custom_create.nil?
+      end
+
+      # Runs this type's entire create/link replacement.
+      # @param realizer [Realizer]
+      # @param node [Node]
+      # @param parent_path [String]
+      # @return [void]
+      def custom_create(realizer, node, parent_path)
+        @custom_create.call(realizer, node, parent_path)
+      end
+
+      # Defines this type's `ui.<type>` method(s) on +mod+ (the {WidgetDSL}
+      # module) - see {WidgetTypes.on_register}, which drives this.
+      # @param mod [Module]
+      # @return [void]
+      def define_dsl_method!(mod)
+        @dsl.call(mod)
+      end
+
+      # Runs this type's post-creation realize setup, if any - a no-op
+      # unless +post_create:+ was given.
+      # @param app [Teek::App]
+      # @param node [Node]
+      # @param path [String]
+      # @param parent_path [String]
+      # @return [void]
+      def post_create(app, node, path, parent_path)
+        @post_create&.call(app, node, path, parent_path)
+      end
+
+      private
+
+      def default_dsl
+        widget_type = self
+        if leaf?
+          ->(mod) {
+            mod.send(:define_method, widget_type.type) { |name = nil, **opts|
+              append_leaf(widget_type.type, name, opts)
+            }
+          }
+        else
+          ->(mod) {
+            mod.send(:define_method, widget_type.type) { |name = nil, **opts, &block|
+              append_container(widget_type.type, name, opts, &block)
+            }
+          }
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+# A canvas is as often fixed drawing as scrollable content, unlike the
+# other natively-scrollable types - scroll_default: points its own
+# auto-scrollable wrapping at Teek::UI.auto_scroll_canvas (false by
+# default) instead of the shared Teek::UI.auto_scroll (true by default)
+# every other natively-scrollable type falls back to.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :canvas, tk_command: 'canvas', leaf: false,
+    natively_scrollable: true, scroll_default: :auto_scroll_canvas
+  )
+)

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

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

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :column, tk_command: 'ttk::frame', leaf: false,
+    flow: {
+      side: 'top', main_pad: :pady, cross_pad: :padx,
+      main_fill: 'y', cross_fill: 'x',
+      anchor: { start: 'w', center: 'center', end: 'e' },
+    }
+  )
+)

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+# See widget_types/menu_bar.rb for the shared reasoning - context_menu is
+# the other entry point into the same Realizer#create_menu_tree traversal,
+# just never attached to a -menu option automatically (popped up via
+# Handle#on_right_click instead).
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :context_menu, tk_command: 'menu', leaf: false, arranged: false,
+    custom_create: ->(realizer, node, parent_path) { realizer.send(:create_menu_tree, node, parent_path) },
+    dsl: ->(mod) { }
+  )
+)

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+# A plain leaf with no bind option, no scrolling, and no realize setup
+# beyond the generic widget-creation command - every field but
+# type/tk_command is a leaf default.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(type: :divider, tk_command: 'ttk::separator')
+)

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

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

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+require_relative '../grid_validator'
+
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :grid, tk_command: 'ttk::frame', leaf: false,
+    arrange: ->(realizer, node, children) { realizer.send(:arrange_grid, node, children) },
+    validator: Teek::UI::GridValidator.method(:call)
+  )
+)

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(type: :group, tk_command: 'ttk::labelframe', leaf: false)
+)

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

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

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

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

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+# menu_bar/context_menu are the two entry points into a menu subtree -
+# everything under them (nested :menu cascades, :menu_item/:menu_separator/
+# :menu_checkbox/:menu_radio entries) is built in one shot by
+# Realizer#create_menu_tree, in menu-add order, rather than through the
+# generic per-node create/link passes every other node type uses - menu
+# entries have no Tk path or geometry-managed arrangement of their own to
+# visit separately, so custom_create: hands the whole thing off (see
+# create_menu_tree's own doc comment for why it also skips #link entirely).
+#
+# tk_command: is documentary only here - create_menu_tree calls
+# Teek::App#menu directly, never the generic tk_command_for path
+# custom_create: bypasses. No auto-generated `ui.menu_bar` method either -
+# it's only ever reachable via the hand-written WidgetDSL#menu_bar, which
+# validates its parent (see WidgetDSL::MENU_BAR_HOSTS); dsl: is a genuine
+# no-op so the registry doesn't shadow that with a same-named generic method.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :menu_bar, tk_command: 'menu', leaf: false, arranged: false,
+    custom_create: ->(realizer, node, parent_path) { realizer.send(:create_menu_tree, node, parent_path) },
+    dsl: ->(mod) { }
+  )
+)

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+require_relative '../menu_entry_addressing'
+
+# See widget_types/menu_item.rb for the shared reasoning - :menu_checkbox
+# is a menu entry kind, addressed the same way (MenuEntryAddressing),
+# reachable only via the hand-written MenuBuilder#checkbox.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :menu_checkbox, tk_command: 'menu', addressing: Teek::UI::MenuEntryAddressing,
+    dsl: ->(mod) { }
+  )
+)

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+require_relative '../menu_entry_addressing'
+
+# :menu_item never flows through the generic Realizer#create path -
+# Realizer#create_menu_tree issues its own `menu add command` call for
+# every :menu_item child directly, so leaf:/arranged:/etc are inert here.
+# Registered so its addressing: (how a named item's Handle reads/writes
+# its live -state/-label/...) is discoverable from the registry, the same
+# way every other type's is - see menu_entry_addressing.rb. No
+# auto-generated `ui.menu_item` method either - it's only ever reachable
+# via the hand-written MenuBuilder#item; dsl: is a genuine no-op so the
+# registry doesn't shadow that with a same-named generic method.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :menu_item, tk_command: 'menu', addressing: Teek::UI::MenuEntryAddressing,
+    dsl: ->(mod) { }
+  )
+)

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+require_relative '../menu_entry_addressing'
+
+# See widget_types/menu_item.rb for the shared reasoning - :menu_radio is
+# a menu entry kind, addressed the same way (MenuEntryAddressing),
+# reachable only via the hand-written MenuBuilder#radio.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :menu_radio, tk_command: 'menu', addressing: Teek::UI::MenuEntryAddressing,
+    dsl: ->(mod) { }
+  )
+)

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

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

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+require_relative '../pane_validator'
+
+module Teek
+  module UI
+    # @api private
+    #
+    # Adds a freshly created :pane's own frame to the enclosing
+    # panedwindow, with whatever `#pane` stashed as pane_weight: (if any).
+    # `ttk::panedwindow add` is the pane's whole placement - unlike every
+    # other container, a pane's frame is never pack/grid-managed on its
+    # own (see :pane's own +arranged: false+ below). Registered as :pane's
+    # own `post_create:`.
+    module PaneRealize
+      def self.post_create(app, node, path, parent_path)
+        weight = node.opts[:pane_weight]
+        opts = weight.nil? ? {} : { weight: weight }
+        app.command(parent_path, :add, path, **opts)
+      end
+    end
+  end
+end
+
+# :pane has no auto-generated `ui.pane` method - it's only ever reachable
+# via the hand-written WidgetDSL#pane, which validates it's declared
+# directly inside ui.split. dsl: is a genuine no-op so the registry
+# doesn't shadow that with a same-named generic method.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :pane, tk_command: 'ttk::frame', leaf: false, arranged: false,
+    post_create: Teek::UI::PaneRealize.method(:post_create),
+    validator: Teek::UI::PaneValidator.method(:call),
+    dsl: ->(mod) { }
+  )
+)

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(type: :panel, tk_command: 'ttk::frame', leaf: false)
+)

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

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

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

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

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :row, tk_command: 'ttk::frame', leaf: false,
+    flow: {
+      side: 'left', main_pad: :padx, cross_pad: :pady,
+      main_fill: 'x', cross_fill: 'y',
+      anchor: { start: 'n', center: 'center', end: 's' },
+    }
+  )
+)

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+# There's no Tk protocol to hook a scrollbar into arbitrary widgets (unlike
+# a natively-scrollable widget's own wrapping - see list.rb/table.rb/etc),
+# so :scrollable's children are created inside an embedded canvas+viewport
+# it builds itself (Realizer#create_scrollable) rather than directly under
+# its own path - custom_children: takes over from the generic
+# "create every child normally" step once its own frame already exists.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :scrollable, tk_command: 'ttk::frame', leaf: false,
+    custom_children: ->(realizer, node, path) { realizer.send(:create_scrollable, node, path) },
+    arrange: ->(realizer, node, children) { realizer.send(:arrange_scrollable_frame, node, children) }
+  )
+)

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

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

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+# A flexible gap - the named replacement for the "invisible spring row"
+# trick (an empty row/column given all the leftover weight). A leaf with
+# `grow: true` baked in and no arguments at all, so it needs its own `dsl:`
+# rather than the generic leaf default (`name = nil, **opts`).
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :spacer, tk_command: 'ttk::frame',
+    dsl: ->(mod) { mod.send(:define_method, :spacer) { append_leaf(:spacer, nil, grow: true) } }
+  )
+)

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+# :split has no auto-generated `ui.split` method - it's only ever reachable
+# via the hand-written WidgetDSL#split, which validates orientation: and
+# translates it to the real -orient option before creating the node.
+# dsl: is a genuine no-op so the registry doesn't shadow that with a
+# same-named generic method. `orient:` itself is a real ttk::panedwindow
+# option, so it needs no reserved-option handling here - it passes through
+# the generic widget-creation call untouched.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :split, tk_command: 'ttk::panedwindow', leaf: false,
+    dsl: ->(mod) { }
+  )
+)

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+require_relative '../tab_validator'
+
+module Teek
+  module UI
+    # @api private
+    #
+    # Adds a freshly created :tab's own frame to the enclosing notebook as
+    # a page, labeled with whatever `#tab` stashed as tab_label:.
+    # `ttk::notebook add` is the page's whole placement - unlike every
+    # other container, a tab's frame is never pack/grid-managed on its own
+    # (see :tab's own +arranged: false+ below). Registered as :tab's own
+    # `post_create:`.
+    module TabRealize
+      def self.post_create(app, node, path, parent_path)
+        app.command(parent_path, :add, path, text: node.opts[:tab_label])
+      end
+    end
+  end
+end
+
+# :tab has no auto-generated `ui.tab` method - it's only ever reachable via
+# the hand-written WidgetDSL#tab, which validates it's declared directly
+# inside ui.tabs. dsl: is a genuine no-op so the registry doesn't shadow
+# that with a same-named generic method.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(
+    type: :tab, tk_command: 'ttk::frame', leaf: false, arranged: false,
+    post_create: Teek::UI::TabRealize.method(:post_create),
+    validator: Teek::UI::TabValidator.method(:call),
+    dsl: ->(mod) { }
+  )
+)

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

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

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative '../widget_type'
+
+# A plain container holding #tab-declared pages - each one placed entirely
+# by `ttk::notebook add` (see tab.rb's own arranged: false), so :tabs
+# itself never has any arrangeable children and needs no custom arrange:.
+Teek::UI::WidgetTypes.register(
+  Teek::UI::WidgetType.new(type: :tabs, tk_command: 'ttk::notebook', leaf: false)
+)