thaum 0.1.0 → 0.2.1

data/examples/todo.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/todo.rb
+#
+# Centered todo card on the Gruvbox Dark theme.
+# - type into the input + Enter to add (input clears)
+# - ↑/↓ moves between the input and the list items
+# - space toggles [ ] / [X]
+# - delete removes the focused item
+# - Tab switches between the input and the Quit button
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+TodoItem = Data.define(:text, :done) do
+  def initialize(text:, done: false)
+    super
+  end
+
+  def toggle = with(done: !done)
+end
+
+class TodoList
+  include Thaum::Sigil
+
+  attr_reader :cursor, :items
+
+  def initialize
+    @items  = []
+    @cursor = 0
+  end
+
+  def add(text)
+    @items << TodoItem.new(text: text)
+  end
+
+  def reset_cursor
+    @cursor = 0
+  end
+
+  def on_key(event)
+    case event.key
+    when :up                  then move_up_or_bubble(event)
+    when :down                then @cursor = (@cursor + 1).clamp(0, [@items.size - 1, 0].max)
+    when " "                  then toggle
+    when :delete, :backspace  then delete_item
+    else emit(event)
+    end
+  end
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    inner = canvas.border(fg: theme.border, style: :rounded)
+    @items.each_with_index do |item, i|
+      row = inner.row(i) or break
+
+      render_item(row, item, focused: focused? && i == @cursor, theme: theme)
+    end
+  end
+
+  private
+
+  def move_up_or_bubble(event)
+    if @cursor.positive?
+      @cursor -= 1
+    else
+      emit(event) # bubble :up so the App can move focus back to the input
+    end
+  end
+
+  def render_item(row, item, focused:, theme:)
+    bg   = focused ? theme.selection : theme.bg
+    fg   = item_fg(item, focused: focused, theme: theme)
+    mark = item.done ? "[X]" : "[ ]"
+    row.fill(bg: bg)
+    row.text(content: " #{mark} #{item.text}", fg: fg, bg: bg)
+  end
+
+  def item_fg(item, focused:, theme:)
+    return theme.success_fg if item.done
+
+    focused ? theme.accent : theme.fg
+  end
+
+  def toggle
+    return if @items.empty?
+
+    @items[@cursor] = @items[@cursor].toggle
+  end
+
+  def delete_item
+    return if @items.empty?
+
+    @items.delete_at(@cursor)
+    @cursor = @cursor.clamp(0, [@items.size - 1, 0].max)
+  end
+end
+
+# Local button that fills its own bg so the card surface stays uniform.
+class ActionButton
+  include Thaum::Sigil
+
+  def initialize(label:)
+    @label = label
+  end
+
+  def on_key(event)
+    case event.key
+    when :enter, " " then emit(Thaum::Button::PressedEvent.new(label: @label))
+    else emit(event)
+    end
+  end
+
+  def render(canvas:, theme:)
+    bg = focused? ? theme.selection : theme.bg
+    fg = focused? ? theme.accent    : theme.fg
+    canvas.fill(bg: bg)
+    canvas.text(content: @label, fg: fg, bg: bg, align: :center)
+  end
+end
+
+class Help
+  include Thaum::Sigil
+
+  LINES = [
+    "↑/↓ navigate   space toggles   delete removes",
+    "tab to Quit   enter adds item   esc quits"
+  ].freeze
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    LINES.each_with_index do |line, i|
+      row = canvas.row(i) or break
+      row.text(content: "  #{line}", fg: theme.info_fg)
+    end
+  end
+end
+
+class Surface
+  include Thaum::Sigil
+
+  def initialize(slot)
+    @slot = slot
+  end
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.send(@slot))
+  end
+end
+
+class TodoApp
+  include Thaum::App
+
+  CARD_WIDTH  = 52
+  CARD_HEIGHT = 18
+
+  def initialize
+    @input = Thaum::TextInput.new
+    @list  = TodoList.new
+    @quit  = ActionButton.new(label: "Quit")
+    @help  = Help.new
+    @pad_l = Surface.new(:bar_bg)
+    @pad_r = Surface.new(:bar_bg)
+    @pad_t = Surface.new(:bar_bg)
+    @pad_b = Surface.new(:bar_bg)
+  end
+
+  def theme = Thaum::Themes::GRUVBOX_DARK
+
+  def on_event(event)
+    case event
+    when Thaum::TextInput::SubmittedEvent then submit(event.value)
+    when Thaum::Button::PressedEvent      then press(event.label)
+    end
+  end
+
+  def on_key(event)
+    case event.key
+    when :escape        then quit
+    when :tab, :backtab then toggle_tab_focus
+    when :down          then down_pressed
+    when :up            then up_pressed
+    end
+  end
+
+  def partition
+    horizontal do
+      region(width: :fill)      { @pad_l }
+      region(width: CARD_WIDTH) { column }
+      region(width: :fill)      { @pad_r }
+    end
+  end
+
+  private
+
+  def column
+    vertical do
+      region(height: :fill)       { @pad_t }
+      region(height: CARD_HEIGHT) { card }
+      region(height: :fill)       { @pad_b }
+    end
+  end
+
+  def card
+    vertical do
+      region(height: 1)     { @input }
+      region(height: :fill) { @list }
+      region(height: 1)     { @quit }
+      region(height: 2)     { @help }
+    end
+  end
+
+  def toggle_tab_focus
+    focus(focused_sigil.equal?(@input) ? @quit : @input)
+  end
+
+  def down_pressed
+    focus(@list) if focused_sigil.equal?(@input) && @list.items.any?
+  end
+
+  def up_pressed
+    focus(@input) if focused_sigil.equal?(@list)
+  end
+
+  def submit(value)
+    value = value.strip
+    return if value.empty?
+
+    @list.add(value)
+    @input.clear
+  end
+
+  def press(label)
+    quit if label == "Quit"
+  end
+end
+
+Thaum.run(TodoApp.new)

data/lib/thaum/action.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Mixin that turns a plain class into a background "action".
+  #
+  # Including this module promotes every *public* instance method into a
+  # class method (see {ClassMethods#method_added}). Calling that class method
+  # schedules the work on the run loop's background thread pool:
+  #
+  #   - A fresh instance is built with an argless `new`, so Actions must not
+  #     require constructor arguments.
+  #   - The method runs fire-and-forget; its return value is discarded.
+  #   - Use {#emit} to push results back to the run loop as events.
+  #   - Calling a promoted method outside a running Thaum app (no pool) raises
+  #     {Thaum::Error}.
+  module Action
+    class << self
+      attr_accessor :queue, :pool
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def emit(event)
+      Thaum::Action.queue&.push(event)
+    end
+
+    module ClassMethods
+      def method_added(name)
+        super
+        return if name == :initialize
+        return unless public_method_defined?(name)
+        return if singleton_class.method_defined?(name, false)
+
+        define_singleton_method(name) do |*args, **kwargs|
+          pool = Thaum::Action.pool
+          unless pool
+            raise Thaum::Error,
+                  "Thaum::Action method called outside a running Thaum app (no thread pool available)"
+          end
+
+          pool.post { new.public_send(name, *args, **kwargs) }
+        end
+      end
+    end
+  end
+end

data/lib/thaum/app.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Thaum
+  module App
+    include Layout
+    include Concerns::Focus
+    include Concerns::ContextUpdate
+    include Concerns::Modal
+    include Concerns::TabNavigation
+
+    attr_reader :in_on_update, :modal_sigil, :modal_rect
+
+    # --- Quit ---
+
+    def quit = (@quit_requested = true)
+    def quit? = @quit_requested
+
+    # --- Render dirty flag ---
+
+    def request_render = (@dirty = true)
+    def dirty? = @dirty
+    def clear_dirty = (@dirty = false)
+
+    # --- Mount wiring ---
+
+    def wire_sigils
+      (@leaf_sigils || []).each { |s| s.thaum_app = self }
+      wire_handler_parents(handler_parent: self, app: self)
+    end
+
+    def thaum_app_ref = self
+
+    # Used by the run loop to seed the initially-focused Sigil before
+    # entering the main loop. Bypasses Focus#focus's mount check because
+    # the mount pass has already run.
+    def set_initial_focus(sigil) = (@focused_sigil = sigil)
+
+    # --- Dispatch from child (synchronous, main thread) ---
+
+    # A child here is either the focused Sigil (when it emits) or the
+    # outermost Octagram (which propagates from its own children). Tab
+    # cycling is intercepted before App#on_key so handlers see :tab with
+    # focus already updated.
+    def dispatch_from_child(event)
+      # When a modal is active, bubbled Tab/Shift-Tab is eaten. Other
+      # bubbled events still reach App handlers — emit from the modal Sigil
+      # can therefore reach App#on_event so apps can react to modal events.
+      return if @modal_sigil && event.is_a?(KeyEvent) && event.key == :tab
+
+      handle_tab_cycle(event) if event.is_a?(KeyEvent) && event.key == :tab
+
+      Dispatch.invoke_handler(target: self, event:, label: "App##{handler_name_for(event)}")
+    end
+    alias dispatch_from_sigil dispatch_from_child
+
+    # --- Theme (override to choose a non-default theme for this app) ---
+
+    def theme = Themes::DEFAULT
+
+    # --- Default App handlers (no-ops — App is top of dispatch chain) ---
+
+    def on_key(event);      end
+    def on_mouse(event);    end
+    def on_paste(event);    end
+    def on_resize(event);   end
+    def on_tick(event);     end
+    def on_mount;           end
+    def on_unmount;         end
+
+    def on_event(event)
+      warn "[Thaum] unhandled event: #{event.class} #{event.inspect}"
+    end
+
+    private
+
+    def focusable_leaves = (@leaf_sigils || []).select(&:focusable?)
+
+    def handler_name_for(event)
+      case event
+      when KeyEvent   then "on_key"
+      when MouseEvent then "on_mouse"
+      when PasteEvent then "on_paste"
+      else                 "on_event"
+      end
+    end
+  end
+end

data/lib/thaum/color.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Capability detection and color-to-escape mapping with degradation
+  # (truecolor → 256 → 16 → none).
+  module Color
+    HEX_COLOR_PATTERN = /\A#[0-9a-fA-F]{6}\z/
+
+    # 16 ANSI color RGB approximations (VGA palette) and their SGR codes
+    # for foreground. Background = fg + 10. Bright = (90 or 100) base.
+    ANSI_16 = {
+      black: { rgb: [0, 0, 0], fg: 30, bg: 40 },
+      red: { rgb: [170, 0, 0], fg: 31, bg: 41 },
+      green: { rgb: [0, 170, 0], fg: 32, bg: 42 },
+      yellow: { rgb: [170, 85, 0], fg: 33, bg: 43 },
+      blue: { rgb: [0,   0, 170], fg: 34, bg: 44 },
+      magenta: { rgb: [170, 0, 170], fg: 35, bg: 45 },
+      cyan: { rgb: [0, 170, 170], fg: 36, bg: 46 },
+      white: { rgb: [170, 170, 170], fg: 37, bg: 47 },
+      bright_black: { rgb: [85, 85, 85], fg: 90, bg: 100 },
+      bright_red: { rgb: [255, 85, 85], fg: 91, bg: 101 },
+      bright_green: { rgb: [85, 255, 85], fg: 92, bg: 102 },
+      bright_yellow: { rgb: [255, 255, 85], fg: 93, bg: 103 },
+      bright_blue: { rgb: [85, 85, 255], fg: 94, bg: 104 },
+      bright_magenta: { rgb: [255, 85, 255], fg: 95, bg: 105 },
+      bright_cyan: { rgb: [85, 255, 255], fg: 96, bg: 106 },
+      bright_white: { rgb: [255, 255, 255], fg: 97, bg: 107 }
+    }.freeze
+
+    def self.detect(env)
+      return :none if no_color?(env)
+
+      colorterm = env["COLORTERM"]
+      term      = env["TERM"]
+      return :truecolor if %w[truecolor 24bit].include?(colorterm)
+      return :none      if term.nil? || term.empty? || term == "dumb"
+      return :"256"     if term.include?("256color")
+
+      :ansi
+    end
+
+    def self.no_color?(env)
+      value = env["NO_COLOR"]
+      !value.nil? && !value.empty?
+    end
+
+    def self.to_escape(color, capability:, base:)
+      return "" if capability == :none
+      return "" if color.nil?
+
+      if color.is_a?(Array)
+        hex, fallback = color
+        return capability == :ansi ? to_escape(fallback, capability:, base:) : to_escape(hex, capability:, base:)
+      end
+
+      case color
+      when Symbol then named_escape(name: color, base: base)
+      when String then hex_escape(hex: color, capability: capability, base: base)
+      else ""
+      end
+    end
+
+    def self.named_escape(name:, base:)
+      info = ANSI_16[name]
+      return "\e[#{base == 38 ? 39 : 49}m" if name == :default
+      return "" unless info
+
+      code = base == 38 ? info[:fg] : info[:bg]
+      "\e[#{code}m"
+    end
+
+    def self.hex_escape(hex:, capability:, base:)
+      return "" unless hex.match?(HEX_COLOR_PATTERN)
+
+      r = hex[1..2].to_i(16)
+      g = hex[3..4].to_i(16)
+      b = hex[5..6].to_i(16)
+
+      case capability
+      when :truecolor then "\e[#{base};2;#{r};#{g};#{b}m"
+      when :"256"     then "\e[#{base};5;#{hex_to_256(r: r, g: g, b: b)}m"
+      when :ansi      then named_escape(name: hex_to_ansi(r: r, g: g, b: b), base: base)
+      else ""
+      end
+    end
+
+    def self.hex_to_256(r:, g:, b:) # rubocop:disable Naming/VariableNumber
+      # 6x6x6 color cube: 16 + 36*r6 + 6*g6 + b6
+      r6 = (r * 5.0 / 255).round
+      g6 = (g * 5.0 / 255).round
+      b6 = (b * 5.0 / 255).round
+      16 + (36 * r6) + (6 * g6) + b6
+    end
+
+    def self.hex_to_ansi(r:, g:, b:)
+      ANSI_16.min_by do |_name, info|
+        ar, ag, ab = info[:rgb]
+        ((r - ar)**2) + ((g - ag)**2) + ((b - ab)**2)
+      end.first
+    end
+
+    private_class_method :no_color?, :named_escape, :hex_escape, :hex_to_256, :hex_to_ansi # rubocop:disable Naming/VariableNumber
+  end
+end

data/lib/thaum/concerns/context_update.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Concerns
+    module ContextUpdate
+      # --- Context ---
+
+      def update_context(hash)
+        cloned = deep_freeze(hash.dup)
+        @context = cloned
+        @in_on_update = true
+        begin
+          Tree.walk(self) do |node|
+            next unless node.is_a?(Sigil) || node.is_a?(Octagram)
+
+            node.on_update(cloned)
+          end
+          # Modal Sigil receives on_update last, after the layout tree.
+          @modal_sigil&.on_update(cloned)
+        ensure
+          @in_on_update = false
+        end
+        request_render
+      end
+
+      private
+
+      def deep_freeze(obj)
+        case obj
+        when Hash
+          obj.transform_values! { |v| deep_freeze(v) }.freeze
+        when Array
+          obj.map! { |v| deep_freeze(v) }.freeze
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/thaum/concerns/focus.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Concerns
+    module Focus
+      # --- Focus ---
+
+      def focus(sigil)
+        return if @modal_sigil
+        return if @focused_sigil.equal?(sigil)
+        return if sigil && !focusable_and_mounted?(sigil)
+
+        old = @focused_sigil
+        @focused_sigil = sigil
+        old&.on_blur
+        sigil&.on_focus
+        request_render
+      end
+
+      def focus_next
+        return if @modal_sigil
+
+        leaves = effective_focus_order
+        return if leaves.empty?
+
+        idx = @focused_sigil ? (leaves.index(@focused_sigil) || -1) : -1
+        focus(leaves[(idx + 1) % leaves.size])
+      end
+
+      def focus_prev
+        return if @modal_sigil
+
+        leaves = effective_focus_order
+        return if leaves.empty?
+
+        idx = @focused_sigil ? (leaves.index(@focused_sigil) || 0) : 0
+        focus(leaves[(idx - 1) % leaves.size])
+      end
+
+      def focused_sigil = @focused_sigil
+
+      def initial_focus
+        (@leaf_sigils || []).find(&:focusable?)
+      end
+
+      private
+
+      def focusable_and_mounted?(sigil)
+        sigil.focusable? && (@leaf_sigils || []).include?(sigil)
+      end
+    end
+  end
+end

data/lib/thaum/concerns/modal.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Concerns
+    module Modal
+      # --- Modal ---
+
+      # Show a modal Sigil as an overlay above the layout tree. width/height
+      # are required; x/y are optional terminal-absolute coords — when nil
+      # the modal is centered on the current terminal size. Calling show_modal
+      # while a modal is already active fires on_blur + on_unmount on the
+      # outgoing modal and replaces it. The previously-focused Sigil (from
+      # before any modal was shown) is preserved so hide_modal can restore it.
+      def show_modal(sigil:, width:, height:, x: nil, y: nil)
+        replacing = !@modal_sigil.nil?
+        centered  = x.nil? && y.nil?
+
+        if replacing
+          Thaum.safe_invoke("#{@modal_sigil.class}#on_blur")    { @modal_sigil.on_blur }
+          Thaum.safe_invoke("#{@modal_sigil.class}#on_unmount") { @modal_sigil.on_unmount }
+          @modal_sigil.thaum_app      = nil
+          @modal_sigil.handler_parent = nil
+          @modal_sigil.rect = nil
+        elsif @focused_sigil
+          # First modal — save the underlying focused Sigil and fire its on_blur.
+          @previous_focus = @focused_sigil
+          Thaum.safe_invoke("#{@focused_sigil.class}#on_blur") { @focused_sigil.on_blur }
+          @focused_sigil = nil
+        end
+
+        rect = compute_modal_rect(width: width, height: height, x: x, y: y)
+
+        @modal_sigil      = sigil
+        @modal_rect       = rect
+        @modal_centered   = centered
+        @modal_decl_w     = width
+        @modal_decl_h     = height
+        sigil.thaum_app      = self
+        sigil.handler_parent = self
+        sigil.rect = rect
+
+        Thaum.safe_invoke("#{sigil.class}#on_mount") { sigil.on_mount }
+        Thaum.safe_invoke("#{sigil.class}#on_focus") { sigil.on_focus }
+
+        request_render
+        sigil
+      end
+
+      def hide_modal
+        sigil = @modal_sigil
+        return unless sigil
+
+        Thaum.safe_invoke("#{sigil.class}#on_blur")    { sigil.on_blur }
+        Thaum.safe_invoke("#{sigil.class}#on_unmount") { sigil.on_unmount }
+
+        @modal_sigil      = nil
+        @modal_rect       = nil
+        @modal_centered   = false
+        @modal_decl_w     = nil
+        @modal_decl_h     = nil
+        sigil.thaum_app      = nil
+        sigil.handler_parent = nil
+        sigil.rect = nil
+
+        restored = @previous_focus
+        @previous_focus = nil
+        if restored && focusable_and_mounted?(restored)
+          @focused_sigil = restored
+          Thaum.safe_invoke("#{restored.class}#on_focus") { restored.on_focus }
+        end
+
+        request_render
+        nil
+      end
+
+      def modal_active? = !@modal_sigil.nil?
+
+      # Called by the framework on ResizeEvent after the layout repartitions.
+      # Re-centers a default-centered modal on the new terminal dimensions.
+      # Modals with explicit x/y stay put.
+      def recompute_modal_rect
+        return unless @modal_sigil && @modal_centered
+
+        @modal_rect = compute_modal_rect(width: @modal_decl_w, height: @modal_decl_h, x: nil, y: nil)
+        @modal_sigil.rect = @modal_rect
+      end
+
+      private
+
+      # Compute the modal's terminal-absolute rect from declared size + optional
+      # x/y. When x/y are nil, centers on the App's current rect (set by
+      # run_partition to the terminal's dimensions). Overflow is allowed —
+      # the Buffer drops out-of-bounds cells at paint time.
+      def compute_modal_rect(width:, height:, x:, y:)
+        app_rect = @rect || Rect.new(x: 0, y: 0, width: 0, height: 0)
+        cx = x.nil? ? app_rect.x + ((app_rect.width  - width)  / 2) : x
+        cy = y.nil? ? app_rect.y + ((app_rect.height - height) / 2) : y
+        Rect.new(x: cx, y: cy, width: width, height: height)
+      end
+    end
+  end
+end