ratatat 1.0.0

data/lib/ratatat/widget.rb

@@ -0,0 +1,337 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Ratatat
+  class QueryError < StandardError; end
+
+  # Base class for all widgets in the UI tree.
+  class Widget
+    extend T::Sig
+    extend Reactive
+
+    CAN_FOCUS = false
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :id
+
+    sig { returns(T::Set[String]) }
+    attr_reader :classes
+
+    sig { returns(T.nilable(Widget)) }
+    attr_reader :parent
+
+    sig { returns(T::Array[Widget]) }
+    attr_reader :children
+
+    sig { returns(Styles) }
+    attr_reader :styles
+
+    sig { params(id: T.nilable(String), classes: T::Array[String], styles: T.nilable(T::Hash[Symbol, T.untyped]), kwargs: T.untyped).void }
+    def initialize(id: nil, classes: [], styles: nil, **kwargs)
+      @id = id
+      @classes = T.let(classes.to_set, T::Set[String])
+      @parent = T.let(nil, T.nilable(Widget))
+      @children = T.let([], T::Array[Widget])
+      @has_focus = T.let(false, T::Boolean)
+      @styles = T.let(styles ? Styles.new(**styles) : Styles.new, Styles)
+
+      # Initialize reactive properties from kwargs
+      kwargs.each do |key, value|
+        setter = :"#{key}="
+        send(setter, value) if respond_to?(setter)
+      end
+    end
+
+    # Class management
+    sig { params(name: String).void }
+    def add_class(name)
+      @classes.add(name)
+    end
+
+    sig { params(name: String).void }
+    def remove_class(name)
+      @classes.delete(name)
+    end
+
+    sig { params(name: String).void }
+    def toggle_class(name)
+      if @classes.include?(name)
+        @classes.delete(name)
+      else
+        @classes.add(name)
+      end
+    end
+
+    sig { params(condition: T::Boolean, name: String).void }
+    def set_class(condition, name)
+      if condition
+        @classes.add(name)
+      else
+        @classes.delete(name)
+      end
+    end
+
+    sig { params(name: String).returns(T::Boolean) }
+    def has_class?(name)
+      @classes.include?(name)
+    end
+
+    # Reactive state for pseudo-classes
+    reactive :disabled, default: false, repaint: true
+    reactive :hover, default: false, repaint: true
+
+    # Trigger repaint (override in subclass or App)
+    sig { void }
+    def refresh
+      # Default: no-op, App overrides to trigger render
+    end
+
+    # Override to define children declaratively
+    sig { returns(T::Array[Widget]) }
+    def compose
+      []
+    end
+
+    # Rebuild children from compose
+    sig { void }
+    def recompose
+      # Remove existing children
+      @children.each { |c| c.instance_variable_set(:@parent, nil) }
+      @children.clear
+
+      # Reset compose flag and re-compose
+      @_composed = nil
+      do_compose
+    end
+
+    # Add children to this widget
+    sig { params(widgets: Widget).returns(T.self_type) }
+    def mount(*widgets)
+      widgets.each do |widget|
+        widget.instance_variable_set(:@parent, self)
+        @children << widget
+        trigger_mount(widget)
+      end
+      self
+    end
+
+    # Remove this widget from its parent
+    sig { void }
+    def remove
+      return unless @parent
+
+      @parent.children.delete(self)
+      @parent = nil
+      trigger_unmount(self)
+    end
+
+    # Get ancestor chain (parent, grandparent, ...)
+    sig { returns(T::Array[Widget]) }
+    def ancestors
+      result = []
+      current = @parent
+      while current
+        result << current
+        current = current.parent
+      end
+      result
+    end
+
+    # Focus management
+    sig { returns(T::Boolean) }
+    def can_focus?
+      # Search class hierarchy for CAN_FOCUS
+      klass = T.let(self.class, T.nilable(T::Class[T.anything]))
+      while klass
+        return klass.const_get(:CAN_FOCUS, false) if klass.const_defined?(:CAN_FOCUS, false)
+        klass = klass.superclass
+      end
+      false
+    end
+
+    sig { returns(T::Boolean) }
+    def has_focus?
+      @has_focus
+    end
+
+    # Request focus for this widget
+    sig { void }
+    def focus
+      return unless can_focus?
+      app&.set_focus(self)
+    end
+
+    # Remove focus from this widget
+    sig { void }
+    def blur
+      return unless @has_focus
+      app&.set_focus(nil)
+    end
+
+    # Find the root App
+    sig { returns(T.nilable(App)) }
+    def app
+      current = T.let(self, T.nilable(Widget))
+      while current
+        return T.cast(current, App) if current.is_a?(App)
+        current = current.parent
+      end
+      nil
+    end
+
+    # Dispatch a message to this widget and bubble up
+    sig { params(message: Message).void }
+    def dispatch(message)
+      # Check key bindings first
+      if message.is_a?(Key) && handle_binding(message)
+        message.stop
+        return
+      end
+
+      handler = handler_for(message)
+      send(handler, message) if handler && respond_to?(handler)
+
+      return if message.stopped? || !message.bubble
+      @parent&.dispatch(message)
+    end
+
+    # Query descendants by selector, returns chainable DOMQuery
+    sig { params(selector: T.any(String, T::Class[Widget])).returns(DOMQuery) }
+    def query(selector)
+      results = T.let([], T::Array[Widget])
+      walk_descendants { |w| results << w if matches?(w, selector) }
+      DOMQuery.new(results)
+    end
+
+    sig { params(selector: T.any(String, T::Class[Widget])).returns(T.nilable(Widget)) }
+    def query_one(selector)
+      query(selector).first
+    end
+
+    sig { params(selector: T.any(String, T::Class[Widget])).returns(Widget) }
+    def query_one!(selector)
+      query_one(selector) || raise(QueryError, "No widget matching: #{selector}")
+    end
+
+    private
+
+    sig { params(message: Message).returns(T.nilable(Symbol)) }
+    def handler_for(message)
+      # Key -> :on_key, Button::Pressed -> :on_button_pressed
+      parts = message.class.name&.split("::")
+      return nil unless parts
+
+      # Remove "Ratatat" prefix if present
+      parts.shift if parts.first == "Ratatat"
+
+      # If nested (e.g., Button::Pressed), use widget_message format
+      name = if parts.length >= 2
+               "#{parts[-2]}_#{parts[-1]}".downcase
+             else
+               parts.last&.downcase
+             end
+
+      return nil unless name
+      :"on_#{name}"
+    end
+
+    sig { params(block: T.proc.params(widget: Widget).void).void }
+    def walk_descendants(&block)
+      @children.each do |child|
+        block.call(child)
+        child.send(:walk_descendants, &block)
+      end
+    end
+
+    sig { params(widget: Widget, selector: T.any(String, T::Class[Widget])).returns(T::Boolean) }
+    def matches?(widget, selector)
+      case selector
+      when String
+        if selector.start_with?("#")
+          widget.id == selector[1..]
+        elsif selector.start_with?(".")
+          widget.classes.include?(selector[1..])
+        else
+          # Type selector - match class name
+          widget.class.name&.split("::")&.last == selector
+        end
+      when Class
+        widget.is_a?(selector)
+      else
+        false
+      end
+    end
+
+    # Check if this widget has BINDINGS and handle the key
+    sig { params(message: Key).returns(T::Boolean) }
+    def handle_binding(message)
+      bindings.each do |binding|
+        if binding.matches?(message.key, message.modifiers)
+          action_method = :"action_#{binding.action}"
+          if respond_to?(action_method)
+            send(action_method)
+            return true
+          end
+        end
+      end
+      false
+    end
+
+    # Get bindings for this widget class
+    sig { returns(T::Array[Binding]) }
+    def bindings
+      return [] unless self.class.const_defined?(:BINDINGS, false)
+
+      raw = self.class.const_get(:BINDINGS, false)
+      raw.map do |b|
+        case b
+        when Binding then b
+        when Array then Binding.new(b[0], b[1], b[2] || "")
+        else b
+        end
+      end
+    end
+
+    sig { params(widget: Widget).void }
+    def trigger_mount(widget)
+      # Only trigger if we're connected to an App
+      return unless widget.app
+      # Skip if already mounted
+      return if widget.instance_variable_get(:@_mounted)
+
+      widget.instance_variable_set(:@_mounted, true)
+
+      # Compose children first (only if not already composed)
+      widget.send(:do_compose) unless widget.instance_variable_get(:@_composed)
+
+      widget.on_mount if widget.respond_to?(:on_mount)
+
+      # Also trigger mount for any pre-existing children (mounted before joining app)
+      widget.children.each { |child| trigger_mount(child) }
+    end
+
+    # Internal: run compose and mount results
+    sig { void }
+    def do_compose
+      return if @_composed
+
+      @_composed = T.let(true, T.nilable(T::Boolean))
+      children = compose
+      return if children.empty?
+
+      children.each do |child|
+        child.instance_variable_set(:@parent, self)
+        @children << child
+        trigger_mount(child) if app
+      end
+    end
+
+    sig { params(widget: Widget).void }
+    def trigger_unmount(widget)
+      widget.children.each { |child| trigger_unmount(child) }
+      widget.on_unmount if widget.respond_to?(:on_unmount)
+    end
+  end
+end

data/lib/ratatat/widgets/button.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Ratatat
+  # Clickable button widget
+  class Button < Widget
+    extend T::Sig
+
+    CAN_FOCUS = true
+
+    # Message emitted when button is activated
+    class Pressed < Message; end
+
+    reactive :label, default: "", repaint: true
+
+    sig { params(label: String, id: T.nilable(String), classes: T::Array[String]).void }
+    def initialize(label = "", id: nil, classes: [])
+      super(id: id, classes: classes)
+      @label = label
+    end
+
+    sig { params(message: Key).void }
+    def on_key(message)
+      if message.key == "enter" || message.key == " "
+        press
+        message.stop
+      end
+    end
+
+    sig { void }
+    def press
+      parent&.dispatch(Pressed.new(sender: self))
+    end
+
+    sig { params(buffer: Buffer, x: Integer, y: Integer, width: Integer, height: Integer).void }
+    def render(buffer, x:, y:, width:, height:)
+      display = "< #{label} >"
+      # Center the button text
+      padding = [(width - display.length) / 2, 0].max
+      buffer.put_string(x + padding, y, display[0, width])
+    end
+  end
+end

data/lib/ratatat/widgets/checkbox.rb

@@ -0,0 +1,68 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Ratatat
+  # Checkbox toggle widget
+  class Checkbox < Widget
+    extend T::Sig
+
+    CAN_FOCUS = true
+
+    # Emitted when checked state changes
+    class Changed < Message
+      extend T::Sig
+
+      sig { returns(T::Boolean) }
+      attr_reader :checked
+
+      sig { params(sender: Widget, checked: T::Boolean).void }
+      def initialize(sender:, checked:)
+        super(sender: sender)
+        @checked = checked
+      end
+    end
+
+    reactive :checked, default: false, repaint: true
+    reactive :label, default: "", repaint: true
+
+    sig { params(label: String, checked: T::Boolean, id: T.nilable(String), classes: T::Array[String]).void }
+    def initialize(label = "", checked: false, id: nil, classes: [])
+      super(id: id, classes: classes)
+      @label = label
+      @checked = checked
+    end
+
+    sig { params(message: Key).void }
+    def on_key(message)
+      if message.key == " " || message.key == "enter"
+        toggle
+        message.stop
+      end
+    end
+
+    sig { void }
+    def toggle
+      self.checked = !checked
+      parent&.dispatch(Changed.new(sender: self, checked: checked))
+    end
+
+    sig { params(buffer: Buffer, x: Integer, y: Integer, width: Integer, height: Integer).void }
+    def render(buffer, x:, y:, width:, height:)
+      indicator = checked ? "[X]" : "[ ]"
+      text = "#{indicator} #{label}"
+      buffer.put_string(x, y, text[0, width])
+    end
+  end
+
+  # Switch toggle widget (alternative visual style)
+  class Switch < Checkbox
+    extend T::Sig
+
+    sig { params(buffer: Buffer, x: Integer, y: Integer, width: Integer, height: Integer).void }
+    def render(buffer, x:, y:, width:, height:)
+      indicator = checked ? "[ON ]" : "[OFF]"
+      text = "#{indicator} #{label}"
+      buffer.put_string(x, y, text[0, width])
+    end
+  end
+end

data/lib/ratatat/widgets/container.rb

@@ -0,0 +1,50 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Ratatat
+  # Generic container widget
+  class Container < Widget
+    extend T::Sig
+
+    sig { params(buffer: Buffer, x: Integer, y: Integer, width: Integer, height: Integer).void }
+    def render(buffer, x:, y:, width:, height:)
+      # Default: render first child with full size
+      return if children.empty?
+
+      child = children.first
+      child.render(buffer, x: x, y: y, width: width, height: height) if child.respond_to?(:render)
+    end
+  end
+
+  # Horizontal layout - children side by side
+  class Horizontal < Widget
+    extend T::Sig
+
+    sig { params(buffer: Buffer, x: Integer, y: Integer, width: Integer, height: Integer).void }
+    def render(buffer, x:, y:, width:, height:)
+      return if children.empty?
+
+      child_width = width / children.length
+      children.each_with_index do |child, i|
+        child_x = x + (i * child_width)
+        child.render(buffer, x: child_x, y: y, width: child_width, height: height) if child.respond_to?(:render)
+      end
+    end
+  end
+
+  # Vertical layout - children stacked
+  class Vertical < Widget
+    extend T::Sig
+
+    sig { params(buffer: Buffer, x: Integer, y: Integer, width: Integer, height: Integer).void }
+    def render(buffer, x:, y:, width:, height:)
+      return if children.empty?
+
+      child_height = height / children.length
+      children.each_with_index do |child, i|
+        child_y = y + (i * child_height)
+        child.render(buffer, x: x, y: child_y, width: width, height: child_height) if child.respond_to?(:render)
+      end
+    end
+  end
+end

data/lib/ratatat/widgets/data_table.rb

@@ -0,0 +1,123 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Ratatat
+  # Tabular data display with navigation
+  class DataTable < Widget
+    extend T::Sig
+
+    CAN_FOCUS = true
+
+    # Emitted when a row is selected (Enter pressed)
+    class RowSelected < Message
+      extend T::Sig
+
+      sig { returns(Integer) }
+      attr_reader :index
+
+      sig { returns(T::Array[String]) }
+      attr_reader :row
+
+      sig { params(sender: Widget, index: Integer, row: T::Array[String]).void }
+      def initialize(sender:, index:, row:)
+        super(sender: sender)
+        @index = index
+        @row = row
+      end
+    end
+
+    sig { returns(T::Array[String]) }
+    attr_reader :columns
+
+    sig { returns(T::Array[T::Array[String]]) }
+    attr_reader :rows
+
+    reactive :cursor_row, default: 0, repaint: true
+
+    sig do
+      params(
+        columns: T::Array[String],
+        rows: T::Array[T::Array[String]],
+        id: T.nilable(String),
+        classes: T::Array[String]
+      ).void
+    end
+    def initialize(columns: [], rows: [], id: nil, classes: [])
+      super(id: id, classes: classes)
+      @columns = columns
+      @rows = T.let(rows.dup, T::Array[T::Array[String]])
+      @cursor_row = 0
+    end
+
+    sig { params(row: T::Array[String]).void }
+    def add_row(row)
+      @rows << row
+      refresh
+    end
+
+    sig { void }
+    def clear_rows
+      @rows.clear
+      @cursor_row = 0
+      refresh
+    end
+
+    sig { params(message: Key).void }
+    def on_key(message)
+      case message.key
+      when "down", "j"
+        move_cursor(1)
+        message.stop
+      when "up", "k"
+        move_cursor(-1)
+        message.stop
+      when "enter"
+        select_row
+        message.stop
+      end
+    end
+
+    sig { params(buffer: Buffer, x: Integer, y: Integer, width: Integer, height: Integer).void }
+    def render(buffer, x:, y:, width:, height:)
+      return if @columns.empty?
+
+      col_width = width / @columns.length
+
+      # Render header
+      @columns.each_with_index do |col, i|
+        buffer.put_string(x + (i * col_width), y, col[0, col_width])
+      end
+
+      # Render rows
+      @rows.each_with_index do |row, row_idx|
+        row_y = y + 1 + row_idx
+        break if row_y >= y + height
+
+        row.each_with_index do |cell, col_idx|
+          break if col_idx >= @columns.length
+
+          prefix = row_idx == @cursor_row ? "> " : "  "
+          text = col_idx == 0 ? "#{prefix}#{cell}" : cell
+          buffer.put_string(x + (col_idx * col_width), row_y, text[0, col_width])
+        end
+      end
+    end
+
+    private
+
+    sig { params(delta: Integer).void }
+    def move_cursor(delta)
+      return if @rows.empty?
+
+      @cursor_row = (@cursor_row + delta).clamp(0, @rows.length - 1)
+    end
+
+    sig { void }
+    def select_row
+      return if @rows.empty? || @cursor_row >= @rows.length
+
+      row = @rows[@cursor_row]
+      parent&.dispatch(RowSelected.new(sender: self, index: @cursor_row, row: row || []))
+    end
+  end
+end

data/lib/ratatat/widgets/grid.rb

@@ -0,0 +1,40 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Ratatat
+  # Grid layout widget
+  class Grid < Widget
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :columns, :gap
+
+    sig { params(columns: Integer, gap: Integer, id: T.nilable(String), classes: T::Array[String]).void }
+    def initialize(columns: 2, gap: 0, id: nil, classes: [])
+      super(id: id, classes: classes)
+      @columns = columns
+      @gap = gap
+    end
+
+    sig { params(buffer: Buffer, x: Integer, y: Integer, width: Integer, height: Integer).void }
+    def render(buffer, x:, y:, width:, height:)
+      return if children.empty?
+
+      col_width = (width - (@gap * (@columns - 1))) / @columns
+      rows = (children.length.to_f / @columns).ceil
+      row_height = rows > 0 ? (height - (@gap * (rows - 1))) / rows : 0
+
+      children.each_with_index do |child, i|
+        col = i % @columns
+        row = i / @columns
+
+        child_x = x + (col * (col_width + @gap))
+        child_y = y + (row * (row_height + @gap))
+
+        break if child_y >= y + height
+
+        child.render(buffer, x: child_x, y: child_y, width: col_width, height: row_height) if child.respond_to?(:render)
+      end
+    end
+  end
+end

data/lib/ratatat/widgets/horizontal.rb

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Ratatat
+  # Horizontal flexbox-like layout widget
+  class Horizontal < Widget
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :gap
+
+    sig { returns(T.nilable(T::Array[Float])) }
+    attr_reader :ratios
+
+    sig { params(gap: Integer, ratios: T.nilable(T::Array[Float]), id: T.nilable(String), classes: T::Array[String]).void }
+    def initialize(gap: 0, ratios: nil, id: nil, classes: [])
+      super(id: id, classes: classes)
+      @gap = gap
+      @ratios = ratios
+    end
+
+    sig { params(buffer: Buffer, x: Integer, y: Integer, width: Integer, height: Integer).void }
+    def render(buffer, x:, y:, width:, height:)
+      return if children.empty?
+
+      total_gap = @gap * (children.length - 1)
+      available_width = width - total_gap
+
+      widths = calculate_widths(available_width)
+      current_x = x
+
+      children.each_with_index do |child, i|
+        child_width = widths[i] || 0
+        child.render(buffer, x: current_x, y: y, width: child_width, height: height) if child.respond_to?(:render)
+        current_x += child_width + @gap
+      end
+    end
+
+    private
+
+    sig { params(available_width: Integer).returns(T::Array[Integer]) }
+    def calculate_widths(available_width)
+      if @ratios && @ratios.length == children.length
+        @ratios.map { |r| (available_width * r).to_i }
+      else
+        # Equal distribution
+        child_width = available_width / children.length
+        Array.new(children.length, child_width)
+      end
+    end
+  end
+end