Module: Charming::Controller::SessionState

Included in:
Charming::Controller
Defined in:
lib/charming/controller/session_state.rb

Overview

Session-state helpers mixed into Controller: accessing the application session hash, lazy state-object lookup by name/class, form builder invocation, and async task submission.

Instance Method Summary collapse

Instance Method Details

#cancel_task(name) ⇒ Object

Cancels the named in-flight background task (raises Tasks::Cancelled inside it). No-op when the task already finished or the executor doesn't support cancellation.



72
73
74
75
 
# File 'lib/charming/controller/session_state.rb', line 72

def cancel_task(name)
  executor = application.task_executor
  executor.cancel(name) if executor.respond_to?(:cancel)
end

#component_state(name, **defaults) ⇒ Object

Returns the named mutable widget-state hash stored under session[:component_state], seeding it from defaults on first access. This is the blessed way to keep an interactive component's state across ephemeral controller instances: store only JSON-safe primitives, rebuild the component from the hash each event, and write changed values back after handle_key. (Live component objects don't belong in the session — save_session drops anything that can't survive a JSON round-trip.)



39
40
41
42
 
# File 'lib/charming/controller/session_state.rb', line 39

def component_state(name, **defaults)
  session[:component_state] ||= {}
  session[:component_state][name.to_sym] ||= defaults
end

#form(name, &block) ⇒ Object

Builds a Form component scoped to the named form slot in session[:forms]. The block is evaluated against a Form::Builder (or invoked with the builder as its argument for arity-1 blocks) and returns a Form component pre-bound to the per-form mutable state hash.



47
48
49
50
51
52
53
 
# File 'lib/charming/controller/session_state.rb', line 47

def form(name, &block)
  session[:forms] ||= {}
  form_state = session[:forms][name.to_sym] ||= {}
  builder = Components::Form::Builder.new(theme: theme)
  block.arity.zero? ? builder.instance_eval(&block) : block.call(builder)
  builder.build(state: form_state, theme: theme)
end

#mouse_targets ⇒ Object

Returns the named layout panes from the latest render.



21
22
23
 
# File 'lib/charming/controller/session_state.rb', line 21

def mouse_targets
  session.fetch(:mouse_targets, [])
end

#register_mouse_targets(targets) ⇒ Object

Stores the named layout panes from the latest render so mouse events can be hit-tested against the same focus slots used by Tab traversal.



16
17
18
 
# File 'lib/charming/controller/session_state.rb', line 16

def register_mouse_targets(targets)
  session[:mouse_targets] = targets
end

#run_task(name, timeout: nil, &block) ⇒ Object

Submits a background task with the given name. The block is executed by the configured task executor; its return value (or any raised exception) is delivered to the controller as a TaskEvent dispatched to the matching on_task handler.

Blocks that accept an argument receive a Tasks::Progress reporter whose report calls dispatch the matching on_task_progress handler. timeout: (seconds) cancels the task with Tasks::Cancelled when exceeded.



62
63
64
65
66
67
68
 
# File 'lib/charming/controller/session_state.rb', line 62

def run_task(name, timeout: nil, &block)
  return application.task_executor.submit(name, timeout: timeout, &block) if timeout

  # Without a timeout, use the plain signature so simple custom executors
  # (`def submit(name, &block)`) remain compatible.
  application.task_executor.submit(name, &block)
end

#session ⇒ Object

Returns the application session hash for this controller. All persistent state (focus, sidebar index, command palette, user state objects) lives here.



10
11
12
 
# File 'lib/charming/controller/session_state.rb', line 10

def session
  application.session
end

#state(name, state_class, **attributes) ⇒ Object

Returns the named session-backed state object, creating it on first access. name is a symbol key under session[:states]. state_class is an ApplicationState subclass whose constructor receives attributes on first creation. Subsequent calls return the same object.



28
29
30
31
 
# File 'lib/charming/controller/session_state.rb', line 28

def state(name, state_class, **attributes)
  session[:states] ||= {}
  session[:states][name.to_sym] ||= state_class.new(**attributes)
end