ratatat 1.0.0

data/lib/ratatat/css_parser.rb

@@ -0,0 +1,192 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Ratatat
+  # Parses CSS-like stylesheets into StyleSheet objects
+  module CSSParser
+    extend T::Sig
+
+    class ParseError < StandardError; end
+
+    sig { params(css: String).returns(StyleSheet) }
+    def self.parse(css)
+      sheet = StyleSheet.new
+      tokens = tokenize(css)
+      parse_rules(tokens, sheet)
+      sheet
+    end
+
+    sig { params(path: String).returns(StyleSheet) }
+    def self.parse_file(path)
+      parse(File.read(path))
+    end
+
+    class << self
+      extend T::Sig
+
+      private
+
+      sig { params(css: String).returns(T::Array[String]) }
+      def tokenize(css)
+        # Remove comments
+        css = css.gsub(%r{/\*.*?\*/}m, "")
+
+        # Split into tokens preserving structure
+        # Only treat : as separator inside blocks (for property:value)
+        tokens = []
+        current = ""
+        in_block = false
+
+        css.each_char do |char|
+          case char
+          when "{"
+            tokens << current.strip unless current.strip.empty?
+            tokens << char
+            current = ""
+            in_block = true
+          when "}"
+            tokens << current.strip unless current.strip.empty?
+            tokens << char
+            current = ""
+            in_block = false
+          when ";"
+            tokens << current.strip unless current.strip.empty?
+            tokens << char
+            current = ""
+          when ":"
+            if in_block
+              # Property:value separator
+              tokens << current.strip unless current.strip.empty?
+              tokens << char
+              current = ""
+            else
+              # Pseudo-class, keep as part of selector
+              current += char
+            end
+          when "\n", "\r"
+            tokens << current.strip unless current.strip.empty?
+            current = ""
+          else
+            current += char
+          end
+        end
+
+        tokens << current.strip unless current.strip.empty?
+        tokens.reject(&:empty?)
+      end
+
+      sig { params(tokens: T::Array[String], sheet: StyleSheet).void }
+      def parse_rules(tokens, sheet)
+        i = 0
+        while i < tokens.length
+          # Find selector
+          selector = tokens[i]
+          break unless selector
+          i += 1
+
+          # Expect {
+          break unless tokens[i] == "{"
+          i += 1
+
+          # Parse properties until }
+          props = {}
+          while i < tokens.length && tokens[i] != "}"
+            prop_name = tokens[i]
+            i += 1
+
+            break unless tokens[i] == ":"
+            i += 1
+
+            # Collect value tokens until ; or }
+            value_tokens = []
+            while i < tokens.length && tokens[i] != ";" && tokens[i] != "}"
+              value_tokens << tokens[i]
+              i += 1
+            end
+
+            # Skip ;
+            i += 1 if tokens[i] == ";"
+
+            prop_sym = prop_name.to_sym
+            value = parse_value(prop_sym, value_tokens.join(" ").strip)
+            props[prop_sym] = value
+          end
+
+          # Skip }
+          i += 1 if tokens[i] == "}"
+
+          sheet.add_rule(selector, **props) unless props.empty?
+        end
+      end
+
+      sig { params(prop: Symbol, value_str: String).returns(T.untyped) }
+      def parse_value(prop, value_str)
+        case prop
+        when :foreground, :background
+          parse_color(value_str)
+        when :width, :height, :min_width, :max_width, :min_height, :max_height
+          value_str.to_i
+        when :padding, :margin
+          parse_spacing(value_str)
+        when :bold, :italic, :underline
+          value_str == "true"
+        when :border, :text_align
+          value_str.to_sym
+        when :border_title
+          value_str
+        else
+          value_str
+        end
+      end
+
+      sig { params(value: String).returns(T.any(Symbol, Color::Rgb)) }
+      def parse_color(value)
+        if value.start_with?("#")
+          parse_hex_color(value)
+        elsif value.start_with?("rgb(")
+          parse_rgb_color(value)
+        else
+          value.to_sym
+        end
+      end
+
+      sig { params(hex: String).returns(Color::Rgb) }
+      def parse_hex_color(hex)
+        hex = hex.delete_prefix("#")
+        r = hex[0..1].to_i(16)
+        g = hex[2..3].to_i(16)
+        b = hex[4..5].to_i(16)
+        Color::Rgb.new(r: r, g: g, b: b)
+      end
+
+      sig { params(rgb: String).returns(Color::Rgb) }
+      def parse_rgb_color(rgb)
+        match = rgb.match(/rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)/)
+        raise ParseError, "Invalid rgb color: #{rgb}" unless match
+
+        Color::Rgb.new(
+          r: match[1].to_i,
+          g: match[2].to_i,
+          b: match[3].to_i
+        )
+      end
+
+      sig { params(value: String).returns(T::Array[Integer]) }
+      def parse_spacing(value)
+        parts = value.split.map(&:to_i)
+        case parts.length
+        when 1
+          [parts[0], parts[0], parts[0], parts[0]]
+        when 2
+          [parts[0], parts[1], parts[0], parts[1]]
+        when 4
+          parts
+        else
+          raise ParseError, "Invalid spacing: #{value}"
+        end
+      end
+    end
+  end
+end

data/lib/ratatat/dom_query.rb

@@ -0,0 +1,124 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Ratatat
+  # Chainable query object for finding widgets in the tree
+  class DOMQuery
+    extend T::Sig
+    include Enumerable
+
+    sig { params(widgets: T::Array[Widget]).void }
+    def initialize(widgets)
+      @widgets = widgets
+    end
+
+    sig { params(selector: String).returns(DOMQuery) }
+    def filter(selector)
+      DOMQuery.new(@widgets.select { |w| matches?(w, selector) })
+    end
+
+    sig { params(selector: String).returns(DOMQuery) }
+    def exclude(selector)
+      DOMQuery.new(@widgets.reject { |w| matches?(w, selector) })
+    end
+
+    sig { returns(T.nilable(Widget)) }
+    def first
+      @widgets.first
+    end
+
+    sig { returns(T.nilable(Widget)) }
+    def last
+      @widgets.last
+    end
+
+    sig { returns(T::Array[Widget]) }
+    def to_a
+      @widgets.dup
+    end
+
+    sig { override.params(block: T.proc.params(arg0: Widget).void).returns(T.untyped) }
+    def each(&block)
+      @widgets.each(&block)
+    end
+
+    sig { returns(Integer) }
+    def count
+      @widgets.length
+    end
+
+    sig { returns(T::Boolean) }
+    def empty?
+      @widgets.empty?
+    end
+
+    # Bulk operations
+
+    # Add a class to all matched widgets
+    sig { params(name: String).returns(DOMQuery) }
+    def add_class(name)
+      @widgets.each { |w| w.add_class(name) }
+      self
+    end
+
+    # Remove a class from all matched widgets
+    sig { params(name: String).returns(DOMQuery) }
+    def remove_class(name)
+      @widgets.each { |w| w.remove_class(name) }
+      self
+    end
+
+    # Toggle a class on all matched widgets
+    sig { params(name: String).returns(DOMQuery) }
+    def toggle_class(name)
+      @widgets.each { |w| w.toggle_class(name) }
+      self
+    end
+
+    # Refresh all matched widgets
+    sig { returns(DOMQuery) }
+    def refresh
+      @widgets.each(&:refresh)
+      self
+    end
+
+    # Remove all matched widgets from their parents
+    sig { returns(DOMQuery) }
+    def remove
+      @widgets.each(&:remove)
+      self
+    end
+
+    # Focus the first matched widget
+    sig { returns(T.nilable(Widget)) }
+    def focus
+      first&.focus
+      first
+    end
+
+    # Set styles on all matched widgets
+    sig { params(props: T.untyped).returns(DOMQuery) }
+    def set_styles(**props)
+      @widgets.each do |w|
+        props.each do |key, value|
+          setter = :"#{key}="
+          w.styles.send(setter, value) if w.styles.respond_to?(setter)
+        end
+      end
+      self
+    end
+
+    private
+
+    sig { params(widget: Widget, selector: String).returns(T::Boolean) }
+    def matches?(widget, selector)
+      if selector.start_with?("#")
+        widget.id == selector[1..]
+      elsif selector.start_with?(".")
+        widget.classes.include?(selector[1..])
+      else
+        widget.class.name&.split("::")&.last == selector
+      end
+    end
+  end
+end

data/lib/ratatat/driver.rb

@@ -0,0 +1,200 @@
+module Ratatat
+  module Driver
+    begin
+      require "ffi"
+    rescue LoadError
+      # FFI gem not available; we'll rely on Native or Null driver.
+    end
+
+    # Pure Ruby driver with cell-based diffing for flicker-free rendering.
+    # This is the recommended driver - no FFI dependencies required.
+    class Native
+      def initialize(io: $stdout, input_io: $stdin)
+        @terminal = Terminal.new(io: io)
+        @input = Input.new(io: input_io)
+        @render_callback = nil
+      end
+
+      def open
+        @terminal.enter
+      end
+
+      def close
+        @terminal.exit
+      end
+
+      # Render lines to terminal using cell-based diffing
+      # Accepts either:
+      # - Array of strings (legacy API)
+      # - Block that draws to buffer (new API)
+      def render(lines = nil, &block)
+        if block_given?
+          @terminal.draw(&block)
+        elsif lines
+          # Legacy API: convert string lines to buffer
+          @terminal.draw do |buffer|
+            lines.each_with_index do |line, y|
+              buffer.put_string(0, y, line)
+            end
+          end
+        end
+      end
+
+      # Poll for keyboard event with timeout (milliseconds)
+      # Returns symbol (:quit, :up, :down, etc.) for compatibility
+      # or KeyEvent for new API
+      def poll_event(timeout_ms = 50)
+        event = @input.poll(timeout_ms / 1000.0)
+        return nil unless event
+
+        # Legacy API compatibility: convert to symbols
+        case event.key
+        when :up then :up
+        when :down then :down
+        when :left then :left
+        when :right then :right
+        when :escape, :q then :quit
+        when :c
+          event.ctrl? ? :quit : nil
+        when :f then :toggle_follow
+        else
+          # Return the KeyEvent for new code
+          event
+        end
+      end
+
+      # Get terminal size as [rows, cols]
+      def size
+        width, height = @terminal.size
+        [height, width]  # Return as [rows, cols] for compatibility
+      end
+
+      # Access to underlying components for advanced usage
+      attr_reader :terminal, :input
+    end
+
+    # A fallback driver that dumps frames to STDOUT; used for specs and when the native
+    # shim is unavailable.
+    class Null
+      def initialize(io: $stdout)
+        @io = io
+        @rows, @cols = detect_size
+      end
+
+      def open; end
+      def close; end
+
+      def render(lines)
+        @io.puts("\e[2J") # clear
+        lines.each { |line| @io.puts(line) }
+      end
+
+      def poll_event(_timeout_ms = 16)
+        nil
+      end
+
+      def size
+        [@rows, @cols]
+      end
+
+      private
+
+      def detect_size
+        require "io/console"
+        rows, cols = IO.console.winsize
+        [rows || 24, cols || 80]
+      rescue LoadError, NoMethodError
+        [24, 80]
+      end
+    end
+
+    # Native driver backed by ratatui via the Rust cdylib.
+    if defined?(FFI)
+      class Ffi
+        extend FFI::Library
+
+        def self.find_lib
+          candidates = []
+          candidates << ENV["RATATAT_NATIVE_PATH"] if ENV["RATATAT_NATIVE_PATH"]
+          base = File.expand_path("../../native/ratatat-ffi/target/release", __dir__)
+          candidates << File.join(base, "libratatat_ffi.dylib")
+          candidates << File.join(base, "libratatat_ffi.so")
+          candidates << "libratatat_ffi"
+          candidates
+        end
+
+        begin
+          ffi_lib(find_lib)
+
+          class Context < FFI::Struct
+            layout :ptr, :pointer
+          end
+
+          class RtEvent < FFI::Struct
+            layout :kind, :int, :code, :uint, :modifiers, :uint
+          end
+
+          attach_function :rt_init, [], :pointer
+          attach_function :rt_shutdown, [:pointer], :void
+          attach_function :rt_render_lines, [:pointer, :pointer, :int], :void
+          attach_function :rt_poll_event, [:pointer, :uint, RtEvent.by_ref], :bool
+          attach_function :rt_size, [:pointer, :pointer, :pointer], :bool
+
+          def initialize
+            @ctx = self.class.rt_init
+          end
+
+          def open; end
+
+          def close
+            self.class.rt_shutdown(@ctx) if @ctx && !@ctx.null?
+            @ctx = nil
+          end
+
+          def render(lines)
+            joined = lines.join("\n") + "\0"
+            ptr = FFI::MemoryPointer.from_string(joined)
+            self.class.rt_render_lines(@ctx, ptr, lines.length)
+          end
+
+          def size
+            rows_ptr = FFI::MemoryPointer.new(:uint)
+            cols_ptr = FFI::MemoryPointer.new(:uint)
+            if self.class.rt_size(@ctx, cols_ptr, rows_ptr)
+              [rows_ptr.read_uint, cols_ptr.read_uint]
+            else
+              [nil, nil]
+            end
+          end
+
+          MOD_CTRL = 0x1
+
+          def poll_event(timeout_ms = 50)
+            evt = RtEvent.new
+            return nil unless self.class.rt_poll_event(@ctx, timeout_ms, evt)
+
+            if evt[:kind] == 1
+              code = evt[:code]
+              mods = evt[:modifiers]
+              if code == "q".ord || (code == "c".ord && (mods & MOD_CTRL) != 0)
+                return :quit
+              elsif code == "f".ord
+                return :toggle_follow
+              elsif code == 1001
+                return :up
+              elsif code == 1002
+                return :down
+              end
+            end
+            nil
+          end
+        rescue LoadError
+          # Native library missing; degrade to null driver.
+          def initialize
+            raise LoadError, "libratatat_ffi not built; run cargo build -p ratatat-ffi --release"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratatat/input.rb

@@ -0,0 +1,208 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Ratatat
+  # Keyboard event representation
+  class KeyEvent < T::Struct
+    extend T::Sig
+
+    const :key, T.any(Symbol, String)
+    const :modifiers, T::Set[Symbol], default: Set.new
+
+    sig { returns(T::Boolean) }
+    def ctrl? = modifiers.include?(:ctrl)
+
+    sig { returns(T::Boolean) }
+    def alt? = modifiers.include?(:alt)
+
+    sig { returns(T::Boolean) }
+    def shift? = modifiers.include?(:shift)
+
+    sig { returns(String) }
+    def to_s
+      mods = modifiers.to_a.map(&:to_s).join("+")
+      mods.empty? ? key.to_s : "#{mods}+#{key}"
+    end
+  end
+
+  # Keyboard input handler with escape sequence parsing
+  class Input
+    extend T::Sig
+
+    # Escape sequence mappings
+    ESCAPE_SEQUENCES = T.let({
+      # Arrow keys
+      "\e[A" => :up,
+      "\e[B" => :down,
+      "\e[C" => :right,
+      "\e[D" => :left,
+
+      # Arrow keys (alternate)
+      "\eOA" => :up,
+      "\eOB" => :down,
+      "\eOC" => :right,
+      "\eOD" => :left,
+
+      # Home/End/Insert/Delete/PageUp/PageDown
+      "\e[H" => :home,
+      "\e[F" => :end,
+      "\e[2~" => :insert,
+      "\e[3~" => :delete,
+      "\e[5~" => :page_up,
+      "\e[6~" => :page_down,
+
+      # Home/End (alternate)
+      "\e[1~" => :home,
+      "\e[4~" => :end,
+      "\eOH" => :home,
+      "\eOF" => :end,
+
+      # Function keys F1-F12
+      "\eOP" => :f1,
+      "\eOQ" => :f2,
+      "\eOR" => :f3,
+      "\eOS" => :f4,
+      "\e[15~" => :f5,
+      "\e[17~" => :f6,
+      "\e[18~" => :f7,
+      "\e[19~" => :f8,
+      "\e[20~" => :f9,
+      "\e[21~" => :f10,
+      "\e[23~" => :f11,
+      "\e[24~" => :f12,
+
+      # Shift+Tab
+      "\e[Z" => :shift_tab
+    }.freeze, T::Hash[String, Symbol])
+
+    # Control character mappings
+    CONTROL_CHARS = T.let({
+      "\x00" => [:space, [:ctrl]],
+      "\x01" => [:a, [:ctrl]],
+      "\x02" => [:b, [:ctrl]],
+      "\x03" => [:c, [:ctrl]],
+      "\x04" => [:d, [:ctrl]],
+      "\x05" => [:e, [:ctrl]],
+      "\x06" => [:f, [:ctrl]],
+      "\x07" => [:g, [:ctrl]],
+      "\x08" => :backspace,
+      "\x09" => :tab,
+      "\x0A" => :enter,
+      "\x0B" => [:k, [:ctrl]],
+      "\x0C" => [:l, [:ctrl]],
+      "\x0D" => :enter,
+      "\x0E" => [:n, [:ctrl]],
+      "\x0F" => [:o, [:ctrl]],
+      "\x10" => [:p, [:ctrl]],
+      "\x11" => [:q, [:ctrl]],
+      "\x12" => [:r, [:ctrl]],
+      "\x13" => [:s, [:ctrl]],
+      "\x14" => [:t, [:ctrl]],
+      "\x15" => [:u, [:ctrl]],
+      "\x16" => [:v, [:ctrl]],
+      "\x17" => [:w, [:ctrl]],
+      "\x18" => [:x, [:ctrl]],
+      "\x19" => [:y, [:ctrl]],
+      "\x1A" => [:z, [:ctrl]],
+      "\x1B" => :escape,
+      "\x7F" => :backspace
+    }.freeze, T::Hash[String, T.any(Symbol, [Symbol, T::Array[Symbol]])])
+
+    sig { returns(IO) }
+    attr_reader :io
+
+    sig { params(io: IO).void }
+    def initialize(io: $stdin)
+      @io = io
+    end
+
+    # Poll for a key event with timeout (in seconds)
+    # Returns KeyEvent or nil if timeout
+    sig { params(timeout_sec: Float).returns(T.nilable(KeyEvent)) }
+    def poll(timeout_sec)
+      ready = IO.select([@io], nil, nil, timeout_sec)
+      return nil unless ready
+
+      read_key
+    end
+
+    # Read a key event (blocking)
+    sig { returns(T.nilable(KeyEvent)) }
+    def read_blocking
+      read_key
+    end
+
+    private
+
+    sig { returns(T.nilable(KeyEvent)) }
+    def read_key
+      char = read_char
+      return nil unless char
+
+      # Check for escape sequence
+      if char == "\e"
+        return parse_escape_sequence
+      end
+
+      # Check for control characters
+      if char.ord < 32 || char.ord == 127
+        return parse_control_char(char)
+      end
+
+      # Regular character
+      KeyEvent.new(key: char)
+    end
+
+    sig { returns(T.nilable(String)) }
+    def read_char
+      @io.read_nonblock(1)
+    rescue IO::WaitReadable, EOFError
+      nil
+    end
+
+    sig { params(timeout_sec: Float).returns(T.nilable(String)) }
+    def read_char_timeout(timeout_sec = 0.01)
+      ready = IO.select([@io], nil, nil, timeout_sec)
+      return nil unless ready
+
+      read_char
+    end
+
+    sig { returns(KeyEvent) }
+    def parse_escape_sequence
+      seq = +"\e"
+
+      5.times do
+        char = read_char_timeout(0.005)
+        break unless char
+
+        seq << char
+
+        if (key = ESCAPE_SEQUENCES[seq])
+          return KeyEvent.new(key: key)
+        end
+
+        if seq.length == 2 && seq[1] != "[" && seq[1] != "O"
+          return KeyEvent.new(key: T.must(seq[1]), modifiers: Set[:alt])
+        end
+      end
+
+      KeyEvent.new(key: :escape)
+    end
+
+    sig { params(char: String).returns(KeyEvent) }
+    def parse_control_char(char)
+      mapping = CONTROL_CHARS[char]
+      return KeyEvent.new(key: :unknown) unless mapping
+
+      if mapping.is_a?(Array)
+        key, mods = mapping
+        KeyEvent.new(key: key, modifiers: mods.to_set)
+      else
+        KeyEvent.new(key: mapping)
+      end
+    end
+  end
+end