chamomile 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f145ff12623c9aed6bee8c47585aea563619d086255be550282ac4df32f2e5b9
-  data.tar.gz: 362dd705d7b703ae247ed844e47a3e679de59fee3d46c4059a01c790a5a13643
+  metadata.gz: cf8690ed6eaa09698bd3a64193250f4caef5ccbda8612da9dffd1f0b5a1125e6
+  data.tar.gz: cce5da2531a8feb9984f18603c722dd522780f2f2ead5075e9d6707a99f8c56d
 SHA512:
-  metadata.gz: 2eb4d188e1d60890e83460e1a7d3d4171622521f87644a78e2d2b1268d8207190b310379fd06ff2d95158f842afa2cdbecb2770c13212b2813658c4f248923f9
-  data.tar.gz: 75314103ae3b836eac6e3de81cb09696ecc647debb1a68f561a23f2e91402676edd10f628da9ae05139c2117549be51a72e2fc18f1b9ce68c0dff8dab6ba0654
+  metadata.gz: ae7732d2962818be4e4441a2a8dfe67b31df0db40fc3c8831e1020521080d90b6308fe235535b2b559bac361ec35e75ed88117396e5382bd2512de659bd1a9d6
+  data.tar.gz: bad50c84d2f86aca40ba4c09bd110aed17cf0c7e7e538aa391990c25b6ab5ed3177919e24843191bd4501267668bfb7a7cf38fb776039970a1d84fad1bc2defb

data/lib/chamomile/application.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Chamomile
+  # Primary mixin for Chamomile applications. Combines Model + Commands
+  # and provides a declarative callback DSL for handling events.
+  #
+  #   class Counter
+  #     include Chamomile::Application
+  #
+  #     def initialize
+  #       @count = 0
+  #     end
+  #
+  #     on_key(:up, "k")  { @count += 1 }
+  #     on_key(:down, "j") { @count -= 1 }
+  #     on_key("q")        { quit }
+  #
+  #     def view
+  #       "Count: #{@count}"
+  #     end
+  #   end
+  module Application
+    # Include Model and Commands into Application itself (not the base class)
+    # so that Application's methods appear earlier in the MRO and can
+    # override Model's default NotImplementedError on update.
+    include Model
+    include Commands
+    include ViewDSL
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Default update that dispatches to DSL-registered handlers.
+    # If a class defines its own `update(msg)`, that takes precedence
+    # over this (standard Ruby MRO).
+    def update(msg)
+      self.class._dispatch_event(self, msg)
+    end
+
+    module ClassMethods
+      # Register a handler for one or more key values.
+      # Keys can be symbols (:up, :down, :enter, etc.) or strings ("q", "k").
+      #
+      #   on_key(:up, "k") { @count += 1 }
+      #   on_key("q") { quit }
+      def on_key(*keys, &block)
+        keys.each do |key|
+          _key_handlers[key] = block
+        end
+      end
+
+      # Register a handler for terminal resize events.
+      #
+      #   on_resize { |e| @width = e.width; @height = e.height }
+      def on_resize(&block)
+        _event_handlers[:resize] = block
+      end
+
+      # Register a handler for tick events.
+      #
+      #   on_tick { refresh_data }
+      def on_tick(&block)
+        _event_handlers[:tick] = block
+      end
+
+      # Register a handler for mouse events.
+      #
+      #   on_mouse { |e| handle_click(e) if e.press? }
+      def on_mouse(&block)
+        _event_handlers[:mouse] = block
+      end
+
+      # Register a handler for focus events.
+      #
+      #   on_focus { @focused = true }
+      def on_focus(&block)
+        _event_handlers[:focus] = block
+      end
+
+      # Register a handler for blur events.
+      #
+      #   on_blur { @focused = false }
+      def on_blur(&block)
+        _event_handlers[:blur] = block
+      end
+
+      # Register a handler for paste events.
+      #
+      #   on_paste { |e| @clipboard = e.content }
+      def on_paste(&block)
+        _event_handlers[:paste] = block
+      end
+
+      # @api private — Key handlers hash (key_value → block)
+      def _key_handlers
+        @_key_handlers ||= {}
+      end
+
+      # @api private — Event handlers hash (event_type → block)
+      def _event_handlers
+        @_event_handlers ||= {}
+      end
+
+      # @api private — Dispatch an event to registered handlers.
+      # Returns command (a callable) or nil.
+      #
+      # The block's return value is the command. If you need to return a command
+      # (like `quit` or `tick`), ensure it is the last expression in the block:
+      #
+      #   on_key("q") { @cleaning_up = true; quit }   # correct — quit is last
+      #   on_key("q") { quit; @cleaning_up = true }   # BUG — quit is discarded
+      #
+      def _dispatch_event(instance, msg)
+        handler = case msg
+                  when KeyEvent    then _key_handlers[msg.key]
+                  when ResizeEvent then _event_handlers[:resize]
+                  when TickEvent   then _event_handlers[:tick]
+                  when MouseEvent  then _event_handlers[:mouse]
+                  when FocusEvent  then _event_handlers[:focus]
+                  when BlurEvent   then _event_handlers[:blur]
+                  when PasteEvent  then _event_handlers[:paste]
+                  end
+
+        return nil unless handler
+
+        result = instance.instance_exec(msg, &handler)
+        # Only return the result if it's a callable command (Proc/Lambda).
+        # Handler blocks often return non-command values (e.g., @count += 1 returns an Integer).
+        result.respond_to?(:call) ? result : nil
+      end
+
+      def inherited(subclass)
+        super
+        # Copy handlers to subclass so parent handlers are inherited
+        subclass.instance_variable_set(:@_key_handlers, _key_handlers.dup)
+        subclass.instance_variable_set(:@_event_handlers, _event_handlers.dup)
+      end
+    end
+  end
+end

data/lib/chamomile/commands.rb

@@ -5,16 +5,30 @@ require "open3"
 
 module Chamomile
   # Internal command types intercepted by Program (not delivered to model)
-  WindowTitleCmd       = Data.define(:title)
-  CursorPositionCmd    = Data.define(:row, :col)
-  CursorShapeCmd       = Data.define(:shape)
-  CursorVisibilityCmd  = Data.define(:visible)
-  ExecCmd              = Data.define(:command, :args, :callback)
-  PrintlnCmd           = Data.define(:text)
+  WindowTitleCommand      = Data.define(:title)
+  WindowTitleCmd          = WindowTitleCommand # backward compat
+
+  CursorPositionCommand   = Data.define(:row, :col)
+  CursorPositionCmd       = CursorPositionCommand # backward compat
+
+  CursorShapeCommand      = Data.define(:shape)
+  CursorShapeCmd          = CursorShapeCommand # backward compat
+
+  CursorVisibilityCommand = Data.define(:visible)
+  CursorVisibilityCmd     = CursorVisibilityCommand # backward compat
+
+  ExecCommand             = Data.define(:command, :args, :callback)
+  ExecCmd                 = ExecCommand # backward compat
+
+  PrintlnCommand          = Data.define(:text)
+  PrintlnCmd              = PrintlnCommand # backward compat
 
   # Internal compound/control command types
-  CancelCmd  = Data.define(:token)
-  StreamCmd  = Data.define(:token, :producer)
+  CancelCommand = Data.define(:token)
+  CancelCmd     = CancelCommand # backward compat
+
+  StreamCommand = Data.define(:token, :producer)
+  StreamCmd     = StreamCommand # backward compat
 
   # Typed envelope for shell command results
   ShellResult = Data.define(:envelope, :stdout, :stderr, :status, :success)
@@ -53,7 +67,7 @@ module Chamomile
   # Helper methods for creating command lambdas (quit, batch, tick, etc.).
   module Commands
     def quit
-      -> { QuitMsg.new }
+      -> { QuitEvent.new }
     end
 
     def none
@@ -74,10 +88,16 @@ module Chamomile
       -> { [:sequence, *valid] }
     end
 
+    # Run commands concurrently (Ruby-idiomatic alias for batch)
+    alias parallel batch
+
+    # Run commands in order (Ruby-idiomatic alias for sequence)
+    alias serial sequence
+
     def tick(duration, &block)
       -> {
         sleep(duration)
-        block ? block.call : TickMsg.new(time: Time.now)
+        block ? block.call : TickEvent.new(time: Time.now)
       }
     end
 
@@ -86,7 +106,7 @@ module Chamomile
         now = Time.now
         next_tick = (now + duration) - (now.to_f % duration)
         sleep(next_tick - Time.now)
-        block ? block.call : TickMsg.new(time: Time.now)
+        block ? block.call : TickEvent.new(time: Time.now)
       }
     end
 
@@ -123,7 +143,7 @@ module Chamomile
 
     # Returns a command that cancels a running token.
     def cancel(token)
-      -> { CancelCmd.new(token: token) }
+      -> { CancelCommand.new(token: token) }
     end
 
     # A streaming command that emits multiple messages over time.
@@ -134,7 +154,7 @@ module Chamomile
       cmd = -> {
         return nil if token.cancelled?
 
-        StreamCmd.new(token: token, producer: block)
+        StreamCommand.new(token: token, producer: block)
       }
       [token, cmd]
     end
@@ -162,32 +182,32 @@ module Chamomile
     end
 
     def window_title(title)
-      -> { WindowTitleCmd.new(title: title) }
+      -> { WindowTitleCommand.new(title: title) }
     end
 
     def cursor_position(row, col)
-      -> { CursorPositionCmd.new(row: row, col: col) }
+      -> { CursorPositionCommand.new(row: row, col: col) }
     end
 
     def cursor_shape(shape)
-      -> { CursorShapeCmd.new(shape: shape) }
+      -> { CursorShapeCommand.new(shape: shape) }
     end
 
     def show_cursor
-      -> { CursorVisibilityCmd.new(visible: true) }
+      -> { CursorVisibilityCommand.new(visible: true) }
     end
 
     def hide_cursor
-      -> { CursorVisibilityCmd.new(visible: false) }
+      -> { CursorVisibilityCommand.new(visible: false) }
     end
 
     def exec(command, *args, &callback)
-      -> { ExecCmd.new(command: command, args: args, callback: callback) }
+      -> { ExecCommand.new(command: command, args: args, callback: callback) }
     end
 
     # Print a line above the rendered TUI area
     def println(text)
-      -> { PrintlnCmd.new(text: text) }
+      -> { PrintlnCommand.new(text: text) }
     end
 
     # Runtime mode toggles — return these as commands from update
@@ -235,7 +255,8 @@ module Chamomile
       -> { RequestWindowSizeMsg.new }
     end
 
-    module_function :quit, :none, :batch, :sequence, :tick, :every, :cmd,
+    module_function :quit, :none, :batch, :sequence, :parallel, :serial,
+                    :tick, :every, :cmd,
                     :deliver, :map, :cancellable, :cancel, :stream,
                     :shell, :timer,
                     :window_title, :cursor_position, :cursor_shape,

data/lib/chamomile/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Chamomile
+  # Block-style configuration for Chamomile.run.
+  #
+  #   Chamomile.run(MyApp.new) do |config|
+  #     config.alt_screen = true
+  #     config.mouse      = :cell_motion
+  #     config.fps        = 30
+  #   end
+  class Configuration
+    attr_accessor :alt_screen, :mouse, :bracketed_paste,
+                  :report_focus, :fps, :catch_panics
+
+    def initialize
+      @alt_screen      = true
+      @mouse           = :none
+      @bracketed_paste = true
+      @report_focus    = false
+      @fps             = 60
+      @catch_panics    = true
+    end
+
+    def to_h
+      {
+        alt_screen: @alt_screen,
+        mouse: @mouse,
+        bracketed_paste: @bracketed_paste,
+        report_focus: @report_focus,
+        fps: @fps,
+        catch_panics: @catch_panics,
+      }
+    end
+  end
+end

data/lib/chamomile/escape_parser.rb

@@ -44,7 +44,7 @@ module Chamomile
 
       @state = GROUND
       @buf.clear
-      yield KeyMsg.new(key: :escape, mod: [])
+      yield KeyEvent.new(key: :escape, mod: [])
     end
 
     private
@@ -72,16 +72,16 @@ module Chamomile
         @state = ESC_SEEN
         @buf = +"\e"
       when "\r", "\n"
-        yield KeyMsg.new(key: :enter, mod: [])
+        yield KeyEvent.new(key: :enter, mod: [])
       when "\t"
-        yield KeyMsg.new(key: :tab, mod: [])
+        yield KeyEvent.new(key: :tab, mod: [])
       when "\x7f", "\x08"
-        yield KeyMsg.new(key: :backspace, mod: [])
+        yield KeyEvent.new(key: :backspace, mod: [])
       when ->(c) { c.ord.between?(1, 26) }
         letter = (ch.ord + 96).chr # \x01 -> 'a', \x02 -> 'b', etc.
-        yield KeyMsg.new(key: letter, mod: [:ctrl])
+        yield KeyEvent.new(key: letter, mod: [:ctrl])
       when ->(c) { c.ord >= 32 }
-        yield KeyMsg.new(key: ch, mod: [])
+        yield KeyEvent.new(key: ch, mod: [])
       end
     end
 
@@ -95,7 +95,7 @@ module Chamomile
         @buf << ch
       when "\e"
         # Another ESC: flush previous ESC as :escape, start new ESC
-        yield KeyMsg.new(key: :escape, mod: [])
+        yield KeyEvent.new(key: :escape, mod: [])
         @buf = +"\e"
         # Stay in ESC_SEEN
       else
@@ -103,16 +103,16 @@ module Chamomile
         @state = GROUND
         @buf.clear
         if ["\x7f", "\x08"].include?(ch)
-          yield KeyMsg.new(key: :backspace, mod: [:alt])
+          yield KeyEvent.new(key: :backspace, mod: [:alt])
         elsif ch.ord >= 32
-          yield KeyMsg.new(key: ch, mod: [:alt])
+          yield KeyEvent.new(key: ch, mod: [:alt])
         elsif ["\r", "\n"].include?(ch)
-          yield KeyMsg.new(key: :enter, mod: [:alt])
+          yield KeyEvent.new(key: :enter, mod: [:alt])
         elsif ch == "\t"
-          yield KeyMsg.new(key: :tab, mod: [:alt])
+          yield KeyEvent.new(key: :tab, mod: [:alt])
         elsif ch.ord.between?(1, 26)
           letter = (ch.ord + 96).chr
-          yield KeyMsg.new(key: letter, mod: %i[alt ctrl])
+          yield KeyEvent.new(key: letter, mod: %i[alt ctrl])
         end
       end
     end
@@ -147,18 +147,18 @@ module Chamomile
       @buf.clear
 
       case ch
-      when "P" then yield KeyMsg.new(key: :f1, mod: [])
-      when "Q" then yield KeyMsg.new(key: :f2, mod: [])
-      when "R" then yield KeyMsg.new(key: :f3, mod: [])
-      when "S" then yield KeyMsg.new(key: :f4, mod: [])
-      when "A" then yield KeyMsg.new(key: :up, mod: [])
-      when "B" then yield KeyMsg.new(key: :down, mod: [])
-      when "C" then yield KeyMsg.new(key: :right, mod: [])
-      when "D" then yield KeyMsg.new(key: :left, mod: [])
-      when "H" then yield KeyMsg.new(key: :home, mod: [])
-      when "F" then yield KeyMsg.new(key: :end_key, mod: [])
+      when "P" then yield KeyEvent.new(key: :f1, mod: [])
+      when "Q" then yield KeyEvent.new(key: :f2, mod: [])
+      when "R" then yield KeyEvent.new(key: :f3, mod: [])
+      when "S" then yield KeyEvent.new(key: :f4, mod: [])
+      when "A" then yield KeyEvent.new(key: :up, mod: [])
+      when "B" then yield KeyEvent.new(key: :down, mod: [])
+      when "C" then yield KeyEvent.new(key: :right, mod: [])
+      when "D" then yield KeyEvent.new(key: :left, mod: [])
+      when "H" then yield KeyEvent.new(key: :home, mod: [])
+      when "F" then yield KeyEvent.new(key: :end_key, mod: [])
       else
-        yield KeyMsg.new(key: seq, mod: [:unknown])
+        yield KeyEvent.new(key: seq, mod: [:unknown])
       end
     end
 
@@ -172,18 +172,18 @@ module Chamomile
 
       if seq == PASTE_END
         # Shouldn't happen in CSI (we'd be in PASTE state), but handle gracefully
-        yield PasteMsg.new(content: @paste_buf.dup)
+        yield PasteEvent.new(content: @paste_buf.dup)
         @paste_buf.clear
         return
       end
 
       # Focus/Blur: \e[I (focus) and \e[O (blur)
       if seq == "\e[I"
-        yield FocusMsg.new
+        yield FocusEvent.new
         return
       end
       if seq == "\e[O"
-        yield BlurMsg.new
+        yield BlurEvent.new
         return
       end
 
@@ -208,11 +208,11 @@ module Chamomile
       when "D" then yield key_with_modifiers(:left, params)
       when "H" then yield key_with_modifiers(:home, params)
       when "F" then yield key_with_modifiers(:end_key, params)
-      when "Z" then yield KeyMsg.new(key: :tab, mod: [:shift]) # Shift+Tab
+      when "Z" then yield KeyEvent.new(key: :tab, mod: [:shift]) # Shift+Tab
       when "~"
         dispatch_tilde(params, &)
       else
-        yield KeyMsg.new(key: seq, mod: [:unknown])
+        yield KeyEvent.new(key: seq, mod: [:unknown])
       end
     end
 
@@ -240,14 +240,14 @@ module Chamomile
               @paste_buf.clear
               return
             when 201
-              yield PasteMsg.new(content: @paste_buf.dup)
+              yield PasteEvent.new(content: @paste_buf.dup)
               @paste_buf.clear
               return
             else
-              return yield KeyMsg.new(key: "\e[#{params.join(";")}~", mod: [:unknown])
+              return yield KeyEvent.new(key: "\e[#{params.join(";")}~", mod: [:unknown])
             end
 
-      yield KeyMsg.new(key: key, mod: mod || [])
+      yield KeyEvent.new(key: key, mod: mod || [])
     end
 
     def dispatch_sgr_mouse(seq)
@@ -283,7 +283,7 @@ module Chamomile
         action = pressed ? MOUSE_PRESS : MOUSE_RELEASE
       end
 
-      yield MouseMsg.new(x: cx, y: cy, button: button, action: action, mod: mod)
+      yield MouseEvent.new(x: cx, y: cy, button: button, action: action, mod: mod)
     end
 
     def paste_char(ch)
@@ -294,13 +294,13 @@ module Chamomile
         content = @paste_buf[0..-(PASTE_END.length + 1)]
         @paste_buf.clear
         @state = GROUND
-        yield PasteMsg.new(content: content)
+        yield PasteEvent.new(content: content)
       elsif @paste_buf.bytesize > MAX_PASTE_SIZE
         # Prevent memory exhaustion — flush what we have and reset
         content = @paste_buf.dup
         @paste_buf.clear
         @state = GROUND
-        yield PasteMsg.new(content: content)
+        yield PasteEvent.new(content: content)
       end
     end
 
@@ -316,9 +316,9 @@ module Chamomile
     def key_with_modifiers(key, params)
       if params.length >= 2
         mod = extract_modifiers(params[1])
-        KeyMsg.new(key: key, mod: mod)
+        KeyEvent.new(key: key, mod: mod)
       else
-        KeyMsg.new(key: key, mod: [])
+        KeyEvent.new(key: key, mod: [])
       end
     end