potty 0.0.1

data/lib/potty/surfaces/inline_surface.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative '../surface'
+
+module Potty
+  module Surfaces
+    # Renders an N-line region in place under the cursor — like docker
+    # compose / npm / cargo progress — instead of taking over the screen.
+    # No init_screen, no alt-screen; the terminal stays in cooked mode, so
+    # Ctrl-C behaves normally and input is left alone (passive widgets only).
+    #
+    # Model: a small cell grid (rows x cols). Widgets draw into it via the
+    # same setpos/addstr/attron calls they use on a curses surface; present
+    # repaints the region with ANSI (carriage-return + clear-line per row,
+    # then cursor back to the top). finalize freezes the last frame and drops
+    # the cursor to the line below so the next prompt lands cleanly.
+    class InlineSurface < Surface
+      SGR_FG = {
+        default: 39, black: 30, red: 31, green: 32, yellow: 33,
+        blue: 34, magenta: 35, cyan: 36, white: 37, bright_black: 90
+      }.freeze
+      SGR_BG = {
+        default: 49, black: 40, red: 41, green: 42, yellow: 43,
+        blue: 44, magenta: 45, cyan: 46, white: 47, bright_black: 100
+      }.freeze
+
+      def initialize(theme:, lines: nil, tick_interval: 40, out: $stdout)
+        super()
+        @theme = theme
+        @rows = [lines || 1, 1].max
+        @tick_interval = tick_interval
+        @out = out
+        @cols = detect_cols
+        @cursor = [0, 0]
+        @cur_style = nil
+        @primed = false
+        erase
+      end
+
+      def size
+        [@rows, @cols]
+      end
+
+      def start
+        @out.write("\e[?25l") # hide cursor
+        @out.flush
+      end
+
+      def finalize
+        present                 # freeze the final frame
+        @out.write("\n")        # drop below the region
+        @out.write("\e[?25h")   # restore cursor
+        @out.flush
+      end
+
+      def erase
+        @cells = Array.new(@rows) { Array.new(@cols) { [' ', nil] } }
+      end
+
+      def setpos(row, col)
+        @cursor = [row, col]
+      end
+
+      def addstr(str)
+        row, col = @cursor
+        return unless row.between?(0, @rows - 1)
+
+        str.to_s.each_char do |ch|
+          break if col >= @cols
+
+          @cells[row][col] = [ch, @cur_style] if col >= 0
+          col += 1
+        end
+        @cursor = [row, col]
+      end
+
+      def attron(style)
+        prev = @cur_style
+        @cur_style = style.is_a?(Potty::Style) ? style : nil
+        yield if block_given?
+      ensure
+        @cur_style = prev
+      end
+
+      def present
+        if @primed
+          @out.write("\e[#{@rows - 1}A") if @rows > 1 # back to the top row
+        else
+          @primed = true
+        end
+
+        @rows.times do |i|
+          @out.write("\r\e[2K") # carriage return + clear line
+          @out.write(render_row(@cells[i]))
+          @out.write("\n") unless i == @rows - 1
+        end
+        @out.flush
+      end
+
+      # Inline mode ignores input; sleeping here gives the loop its tick
+      # cadence. Terminal stays cooked, so Ctrl-C raises Interrupt normally.
+      def read_key
+        sleep(@tick_interval / 1000.0) if @tick_interval
+        nil
+      end
+
+      private
+
+      def render_row(cells)
+        last = cells.rindex { |ch, _| ch != ' ' } || -1
+        return '' if last.negative?
+
+        out = +''
+        emitted = nil
+        (0..last).each do |i|
+          ch, style = cells[i]
+          if style != emitted
+            out << sgr(style)
+            emitted = style
+          end
+          out << ch
+        end
+        out << "\e[0m" if emitted
+        out
+      end
+
+      def sgr(style)
+        return "\e[0m" if style.nil?
+
+        codes = []
+        codes << 1 if style.bold?
+        codes << 4 if style.underline?
+        codes << 7 if style.reverse?
+        codes << SGR_FG.fetch(style.fg, 39)
+        codes << SGR_BG.fetch(style.bg, 49)
+        "\e[#{codes.join(';')}m"
+      end
+
+      def detect_cols
+        return @out.winsize[1] if @out.respond_to?(:winsize) && @out.tty?
+
+        (ENV['COLUMNS'] || 80).to_i
+      rescue StandardError
+        80
+      end
+    end
+  end
+end

data/lib/potty/theme.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'curses'
+require_relative 'style'
+
+module Potty
+  # Theme maps semantic names to colours, and speaks two dialects:
+  #
+  #   theme.style(:info)  => a Style (symbolic, render-target-agnostic) —
+  #                          the path Surfaces resolve, for curses OR inline.
+  #   theme[:info]        => a curses attribute integer (a colour pair) —
+  #                          back-compat for code that draws straight to a
+  #                          Curses window. Only meaningful once curses is up.
+  #
+  # The symbolic PALETTE is the source of truth; the curses pairs are derived
+  # from it in setup_colors, so the two dialects never drift.
+  class Theme
+    # Symbolic colour names -> curses colour numbers (-1 = terminal default).
+    COLORS = {
+      default: -1,
+      black: ::Curses::COLOR_BLACK,   red: ::Curses::COLOR_RED,
+      green: ::Curses::COLOR_GREEN,   yellow: ::Curses::COLOR_YELLOW,
+      blue: ::Curses::COLOR_BLUE,     magenta: ::Curses::COLOR_MAGENTA,
+      cyan: ::Curses::COLOR_CYAN,     white: ::Curses::COLOR_WHITE,
+      bright_black: 8
+    }.freeze
+
+    # name -> { fg:, bg: } in symbolic colours. Body text inherits the
+    # terminal's own colours (:default) so potty blends into any theme;
+    # only deliberate highlights carry an explicit background.
+    PALETTE = {
+      normal:   { fg: :default,      bg: :default },
+      selected: { fg: :black,        bg: :green },
+      disabled: { fg: :bright_black, bg: :default },
+      success:  { fg: :green,        bg: :default },
+      error:    { fg: :red,          bg: :default },
+      warning:  { fg: :yellow,       bg: :default },
+      info:     { fg: :cyan,         bg: :default },
+      dim:      { fg: :bright_black, bg: :default },
+      header:   { fg: :white,        bg: :blue },
+      status:   { fg: :black,        bg: :cyan }
+    }.freeze
+
+    attr_reader :palette, :colors
+
+    # Pass a partial palette ({ name => { fg:, bg: } }) to override entries.
+    def initialize(palette = nil)
+      @palette = palette ? PALETTE.merge(palette) : PALETTE
+      @colors = {}
+      setup_colors if ::Curses.has_colors?
+    end
+
+    # Allocate a curses colour pair per palette entry (curses mode only).
+    def setup_colors
+      ::Curses.start_color
+      ::Curses.use_default_colors
+      @palette.each_with_index do |(name, c), idx|
+        pair = idx + 1
+        ::Curses.init_pair(pair, COLORS.fetch(c[:fg], -1), COLORS.fetch(c[:bg], -1))
+        @colors[name] = ::Curses.color_pair(pair)
+      end
+    end
+
+    # Semantic style — symbolic colours + attributes, resolved by a Surface.
+    def style(name, bold: false, underline: false, reverse: false)
+      c = @palette[name] || @palette[:normal]
+      Style.new(fg: c[:fg], bg: c[:bg], bold: bold, underline: underline, reverse: reverse)
+    end
+
+    # Curses attribute integer (back-compat for direct-to-window drawing).
+    def [](name)
+      @colors[name] || @colors[:normal] || 0
+    end
+
+    def attr(name, bold: false, underline: false)
+      a = self[name]
+      a |= ::Curses::A_BOLD if bold
+      a |= ::Curses::A_UNDERLINE if underline
+      a
+    end
+  end
+end

data/lib/potty/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Potty
+  VERSION = '0.0.1'
+end

data/lib/potty/view.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative 'layout'
+require_relative 'keys'
+
+module Potty
+  # Base class for views
+  class View
+    attr_reader :app, :widgets
+
+    def initialize(app)
+      @app = app
+      @widgets = []
+      @focused_index = 0
+      build_layout
+    end
+
+    def activate(app)
+      @app = app
+      on_activate
+      layout_widgets
+    end
+
+    def deactivate
+      on_deactivate
+    end
+
+    def on_activate; end
+    def on_deactivate; end
+
+    # Override to build widget tree
+    def build_layout
+      # Override in subclasses
+    end
+
+    def layout_widgets
+      rows, cols = @app.surface.size
+      container = Layout::Rect.new(0, 0, cols, rows)
+
+      # Simple stack layout with spacing
+      rects = Layout.stack(container, @widgets, spacing: 1)
+      @widgets.zip(rects).each do |widget, rect|
+        widget.layout(rect)
+      end
+    end
+
+    # Draw the widget tree onto the application's surface. The surface frame
+    # (erase/present) is owned by Application#refresh_all, so this just paints.
+    def render
+      surface = @app.surface
+      @widgets.each do |widget|
+        widget.render(surface)
+      end
+    end
+
+    # Fan a time tick out to top-level widgets. Driven by Application#tick
+    # when a tick_interval is set. `now` is one Time read per frame.
+    def tick(now)
+      @widgets.each { |widget| widget.tick(now) }
+    end
+
+    def handle_key(ch)
+      # Delegate to focused widget first
+      return true if focused_widget&.handle_key(ch)
+
+      # Handle view-level keys
+      case ch
+      when Keys::TAB
+        cycle_focus(1)
+        true
+      when Keys::SHIFT_TAB
+        cycle_focus(-1)
+        true
+      else
+        false
+      end
+    end
+
+    def handle_escape
+      false  # Return true if handled
+    end
+
+    protected
+
+    def flash_success(message)
+      flash_widget&.show(message, type: :success)
+    end
+
+    def flash_error(message)
+      flash_widget&.show(message, type: :error)
+    end
+
+    def flash_info(message)
+      flash_widget&.show(message, type: :info)
+    end
+
+    def flash_widget
+      @widgets.find { |w| w.is_a?(Widgets::FlashMessage) }
+    end
+
+    private
+
+    # Focusable leaves in visual order, recursing into containers so a
+    # nested layout (VBox/HBox/Panel) still cycles correctly with Tab.
+    def focusable_widgets
+      @widgets.flat_map do |w|
+        if w.is_a?(Widgets::Container)
+          w.focusable_widgets
+        elsif w.can_focus?
+          [w]
+        else
+          []
+        end
+      end
+    end
+
+    def cycle_focus(delta)
+      focusable = focusable_widgets
+      return if focusable.empty?
+
+      current = focusable.index(focused_widget) || 0
+      new_index = (current + delta) % focusable.size
+
+      focused_widget&.blur
+      focusable[new_index].focus
+    end
+
+    def focused_widget
+      focusable_widgets.find(&:focused)
+    end
+  end
+end

data/lib/potty/widgets/base.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative '../events'
+
+module Potty
+  module Widgets
+    # Base class for all widgets
+    class Base
+      include Events
+
+      attr_accessor :rect, :parent, :focused
+      attr_reader :app
+
+      def initialize(app)
+        @app = app
+        @rect = nil
+        @parent = nil
+        @focused = false
+        @visible = true
+      end
+
+      # Lifecycle
+      def activate
+        # Override in subclasses
+      end
+
+      def deactivate
+        # Override in subclasses
+      end
+
+      # Layout
+      def preferred_height(width)
+        1  # Default to single line
+      end
+
+      def layout(rect)
+        @rect = rect
+        on_layout
+      end
+
+      def on_layout
+        # Override for custom layout logic
+      end
+
+      # Rendering
+      def render(window)
+        return unless @visible && @rect
+        # Override in subclasses
+      end
+
+      # Time-based update hook. Called once per event-loop frame when the
+      # Application has a tick_interval set. `now` is a single Time read
+      # shared across all widgets in the frame (so playback stays in sync
+      # and is deterministic to unit-test). Override in time-driven widgets
+      # such as Animator and Countdown.
+      def tick(now)
+        # Override in time-driven subclasses
+      end
+
+      # Input
+      def handle_key(ch)
+        false  # Return true if handled
+      end
+
+      def handle_escape
+        false  # Return true if handled
+      end
+
+      # Focus
+      def can_focus?
+        false  # Override in interactive widgets
+      end
+
+      def focus
+        @focused = true
+        on_focus
+        emit(:focus, self)
+      end
+
+      def blur
+        @focused = false
+        on_blur
+        emit(:blur, self)
+      end
+
+      def on_focus; end
+      def on_blur; end
+
+      # Visibility
+      def visible?
+        @visible
+      end
+
+      def show
+        @visible = true
+        self
+      end
+
+      def hide
+        @visible = false
+        self
+      end
+
+      def visible=(flag)
+        flag ? show : hide
+      end
+
+      # Helpers
+      def theme
+        @app.theme
+      end
+    end
+  end
+end

data/lib/potty/widgets/button.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../keys'
+
+module Potty
+  module Widgets
+    # Focusable push button. Space/Enter fires :press. Pass on_press: for a
+    # one-liner, or wire it with button.on(:press) { ... }.
+    class Button < Base
+      attr_accessor :label, :color
+
+      def initialize(app, label: '', color: :normal, on_press: nil)
+        super(app)
+        @label = label
+        @color = color
+        on(:press, &on_press) if on_press
+      end
+
+      def can_focus?
+        true
+      end
+
+      def preferred_height(_width)
+        1
+      end
+
+      def press
+        emit(:press, self)
+      end
+
+      def handle_key(ch)
+        case ch
+        when Keys::SPACE, *Keys::ENTERS
+          press
+          true
+        else
+          false
+        end
+      end
+
+      def render(window)
+        return unless @visible && @rect
+
+        text = "[ #{@label} ]"[0, @rect.width]
+        attr = @focused ? theme.attr(:selected, bold: true) : theme[@color]
+        window.setpos(@rect.y, @rect.x)
+        window.attron(attr) { window.addstr(text) }
+      end
+    end
+  end
+end

data/lib/potty/widgets/checkbox_group.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'curses'
+require_relative 'base'
+require_relative '../keys'
+
+module Potty
+  module Widgets
+    # Multi-select list of options, one row each. Up/down move a cursor,
+    # Space/Enter toggles the option under it. The RadioGroup sibling for
+    # "choose any number". Emits :change(selected_values) on each toggle.
+    class CheckboxGroup < Base
+      attr_accessor :on_change
+
+      def initialize(app, options: [], selected: [], on_change: nil)
+        super(app)
+        @options = normalize(options)
+        @selected = Array(selected).dup
+        @cursor = 0
+        @on_change = on_change
+      end
+
+      def can_focus?
+        true
+      end
+
+      def options
+        @options
+      end
+
+      # A snapshot of the selected values (safe to store).
+      def selected
+        @selected.dup
+      end
+
+      def selected?(value)
+        @selected.include?(value)
+      end
+
+      def preferred_height(_width)
+        @options.size
+      end
+
+      def handle_key(ch)
+        case ch
+        when Keys::UP
+          move(-1)
+        when Keys::DOWN
+          move(1)
+        when Keys::SPACE, *Keys::ENTERS
+          toggle(@cursor)
+        else
+          return false
+        end
+        true
+      end
+
+      def render(window)
+        return unless @visible && @rect
+
+        @options.each_with_index do |opt, i|
+          break if i >= @rect.height
+
+          mark = selected?(opt[:value]) ? "[\u2713]" : "[ ]"
+          on_cursor = @focused && i == @cursor
+          attr = on_cursor ? theme.attr(:selected, bold: true) : theme[:normal]
+          window.setpos(@rect.y + i, @rect.x)
+          window.attron(attr) { window.addstr("#{mark} #{opt[:label]}"[0, @rect.width]) }
+        end
+      end
+
+      private
+
+      def normalize(opts)
+        (opts || []).map do |o|
+          if o.is_a?(Hash)
+            { value: o[:value], label: (o[:label] || o[:value]).to_s }
+          else
+            { value: o, label: o.to_s }
+          end
+        end
+      end
+
+      def move(delta)
+        return if @options.empty?
+
+        @cursor = (@cursor + delta) % @options.size
+      end
+
+      def toggle(idx)
+        opt = @options[idx]
+        return unless opt
+
+        value = opt[:value]
+        selected?(value) ? @selected.delete(value) : (@selected << value)
+        @on_change&.call(selected)
+        emit(:change, selected)
+      end
+    end
+  end
+end

data/lib/potty/widgets/colored_fields_item.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'list_item'
+
+module Potty
+  module Widgets
+    # Generic multi-color list item
+    # Takes an array of segments, each with text and color, and renders them inline
+    #
+    # Usage:
+    #   item = ColoredFieldsItem.new(
+    #     fields: [
+    #       { text: "[M]", color: :success },
+    #       { text: " " },
+    #       { text: "[0]", color: :dim },
+    #       { text: " /path/to/backup", color: :normal }
+    #     ],
+    #     value: some_object
+    #   ) { |item| handle_activation(item) }
+    #
+    class ColoredFieldsItem < ActionItem
+      attr_reader :fields
+
+      def initialize(fields:, value: nil, &action)
+        @fields = fields
+        super("", value: value, &action)
+      end
+
+      def render_custom(window, theme, max_width)
+        remaining = max_width
+        @fields.each do |field|
+          break if remaining <= 0
+
+          text = field[:text] || ""
+          color = field[:color]
+          bold = field[:bold] || false
+
+          text = text[0, remaining]
+
+          if color
+            attr = bold ? theme.attr(color, bold: true) : theme[color]
+            window.attron(attr) do
+              window.addstr(text)
+            end
+          else
+            window.addstr(text)
+          end
+
+          remaining -= text.length
+        end
+
+        true
+      end
+    end
+  end
+end