Module: Thaum::Octagram

Includes:
Concerns::Layout
Defined in:
lib/thaum/octagram.rb

Overview

A composite container — a distributable component that owns both layout (Layout DSL) and behavior (Sigil-like handlers). Sits between its child Sigils and the App in the dispatch chain: when a focused child Sigil emits, the innermost enclosing Octagram’s handler runs first, and propagates upward only if it calls emit.

See DECISIONS.md (2026-06-02) for the naming rationale.

Instance Attribute Summary collapse

Attributes included from Concerns::Layout

#child_layouts, #leaf_sigils, #rect, #subtree_children, #subtree_leaves

Instance Method Summary collapse

Methods included from Concerns::Layout

#collect_octagrams, #effective_focus_order, #first_focusable_leaf, #focus_order, #focus_scope_units, #focusable_descendant?, #inset_for_partition, #last_focusable_leaf, #layout_subtree_in_order, #partition, #repartition, #run_partition, #validate_focus_order_tree, #wire_handler_parents

Instance Attribute Details

#handler_parent ⇒ Object

Returns the value of attribute handler_parent.



14
15
16
 
# File 'lib/thaum/octagram.rb', line 14

def handler_parent
  @handler_parent
end

#thaum_app ⇒ Object

Returns the value of attribute thaum_app.



14
15
16
 
# File 'lib/thaum/octagram.rb', line 14

def thaum_app
  @thaum_app
end

Instance Method Details

#dispatch_from_child(event) ⇒ Object

Called by a child Sigil (or nested Octagram) when it emits.



61
62
63
 
# File 'lib/thaum/octagram.rb', line 61

def dispatch_from_child(event)
  Dispatch.invoke_handler(target: self, event: event, label: "#{self.class}##{handler_name_for(event)}")
end

#emit(event) ⇒ Object

Propagate an event to this Octagram’s handler parent. Mirrors Sigil#emit: drops framework-internal events and respects the emit-from-on_update guard.

Raises:



47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/thaum/octagram.rb', line 47

def emit(event)
  app = @thaum_app or return
  raise Thaum::EmitFromUpdateError, "emit called from on_update" if app.in_on_update

  if event.is_a?(Thaum::TickEvent) || event.is_a?(Thaum::ResizeEvent)
    warn "[Thaum] dropping #{event.class} from #{self.class}: " \
         "framework-internal events cannot be emitted from Sigils or Actions"
    return
  end

  (@handler_parent || app).dispatch_from_child(event)
end

#octagram? ⇒ Boolean

Marker so the framework’s tree-walks can distinguish Octagrams from plain Layouts (which don’t participate in event dispatch).

Returns:

  • (Boolean) 


18
 
# File 'lib/thaum/octagram.rb', line 18

def octagram? = true

#on_event(event) ⇒ Object 



36
 
# File 'lib/thaum/octagram.rb', line 36

def on_event(event) = emit(event)

#on_key(event) ⇒ Object

Handlers — same shape as Sigil. Defaults propagate to the handler parent (the next outer Octagram, or the App).



33
 
# File 'lib/thaum/octagram.rb', line 33

def on_key(event)   = emit(event)

#on_mount ⇒ Object

Lifecycle — overridable.



39
 
# File 'lib/thaum/octagram.rb', line 39

def on_mount;             end

#on_mouse(event) ⇒ Object 



34
 
# File 'lib/thaum/octagram.rb', line 34

def on_mouse(event) = emit(event)

#on_paste(event) ⇒ Object 



35
 
# File 'lib/thaum/octagram.rb', line 35

def on_paste(event) = emit(event)

#on_tick(event) ⇒ Object 



42
 
# File 'lib/thaum/octagram.rb', line 42

def on_tick(event);       end

#on_unmount ⇒ Object 



40
 
# File 'lib/thaum/octagram.rb', line 40

def on_unmount;           end

#on_update(context) ⇒ Object 



41
 
# File 'lib/thaum/octagram.rb', line 41

def on_update(context);   end

#partition_inset ⇒ Object

Override to inset the rect the Octagram’s children partition into, so the render hook above is not overwritten by child rendering. Return a Hash with any of :top, :bottom, :left, :right keys (each an Integer; missing keys default to 0). For a 1-cell border on all sides, return { top: 1, bottom: 1, left: 1, right: 1 }.



29
 
# File 'lib/thaum/octagram.rb', line 29

def partition_inset = nil

#render(canvas:, theme:) ⇒ Object

Optional background — drawn before the Octagram’s child sigils. Override to paint a frame, border, or fill behind the children.



22
 
# File 'lib/thaum/octagram.rb', line 22

def render(canvas:, theme:); end