potty 0.0.1

data/lib/potty/widgets/container.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../layout'
+
+module Potty
+  module Widgets
+    # A widget that holds child widgets and lays them out within its own
+    # rect. Render, tick, and focus traversal recurse into children, so a
+    # View's flat `@widgets` array can now contain arbitrarily nested
+    # structure (a VBox of HBoxes of fields, etc.) while the View itself
+    # stays unchanged.
+    #
+    # Subclasses implement `layout_children` (assign each child a rect) and
+    # `preferred_height`.
+    class Container < Base
+      attr_reader :children
+
+      def initialize(app, spacing: 0)
+        super(app)
+        @children = []
+        @spacing = spacing
+      end
+
+      def add(*widgets)
+        widgets.flatten.each do |w|
+          w.parent = self
+          @children << w
+        end
+        self
+      end
+      alias << add
+
+      # Focusable leaf descendants, in visual order (depth-first).
+      def focusable_widgets
+        @children.flat_map do |child|
+          if child.is_a?(Container)
+            child.focusable_widgets
+          elsif child.can_focus?
+            [child]
+          else
+            []
+          end
+        end
+      end
+
+      def on_layout
+        layout_children
+      end
+
+      # Override in subclasses.
+      def layout_children
+        # no-op
+      end
+
+      def render(window)
+        return unless @visible && @rect
+
+        @children.each { |child| child.render(window) if child.visible? }
+      end
+
+      def tick(now)
+        @children.each { |child| child.tick(now) }
+      end
+    end
+
+    # Vertical stack — children top to bottom, each at its preferred height.
+    class VBox < Container
+      def preferred_height(width)
+        return 0 if @children.empty?
+
+        @children.sum { |c| c.preferred_height(width) } + @spacing * (@children.size - 1)
+      end
+
+      def layout_children
+        rects = Layout.stack(@rect.dup, @children, spacing: @spacing)
+        @children.zip(rects).each { |child, rect| child.layout(rect) }
+      end
+    end
+
+    # Horizontal row — children share the width in equal columns (the last
+    # absorbs rounding), each spanning the full height.
+    class HBox < Container
+      def preferred_height(width)
+        return 0 if @children.empty?
+
+        @children.map { |c| c.preferred_height(child_width(width)) }.max
+      end
+
+      def layout_children
+        n = @children.size
+        return if n.zero?
+
+        base = child_width(@rect.width)
+        x = @rect.x
+        @children.each_with_index do |child, i|
+          w = i == n - 1 ? (@rect.x + @rect.width - x) : base
+          child.layout(Layout::Rect.new(x, @rect.y, w, @rect.height))
+          x += w + @spacing
+        end
+      end
+
+      private
+
+      def child_width(width)
+        n = @children.size
+        return width if n.zero?
+
+        [(width - @spacing * (n - 1)) / n, 1].max
+      end
+    end
+  end
+end

data/lib/potty/widgets/countdown.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Potty
+  module Widgets
+    # Passive display that counts down from N seconds and fires on_expire
+    # once when it reaches zero. Time-driven: it advances off the `now`
+    # passed to tick(now), so drive it via the Application tick loop
+    # (set Application#tick_interval).
+    #
+    # The clock starts on the first tick (not at construction), so a
+    # Countdown built well before the loop spins up still gets its full N.
+    class Countdown < Base
+      attr_accessor :on_expire
+
+      def initialize(app, seconds:, on_expire: nil, format: nil)
+        super(app)
+        @seconds = seconds.to_f
+        @on_expire = on_expire
+        @format = format || ->(remaining) { "Auto-launching in #{remaining}s\u2026" }
+        @started_at = nil
+        @last_now = nil
+        @running = true
+        @expired = false
+      end
+
+      # (Re)start the countdown from the top.
+      def start
+        @started_at = nil
+        @last_now = nil
+        @running = true
+        @expired = false
+        self
+      end
+
+      def stop
+        @running = false
+        self
+      end
+
+      def expired?
+        @expired
+      end
+
+      # Whole seconds left (ceil), clamped at 0.
+      def remaining
+        return @seconds.ceil if @started_at.nil? || @last_now.nil?
+
+        [@seconds - (@last_now - @started_at), 0].max.ceil
+      end
+
+      def preferred_height(_width)
+        1
+      end
+
+      def tick(now)
+        @last_now = now
+        return unless @running
+
+        @started_at ||= now
+        return if @expired
+
+        return unless now - @started_at >= @seconds
+
+        @expired = true
+        @running = false
+        @on_expire&.call(self)
+        emit(:expire, self)
+      end
+
+      def render(window)
+        return unless @visible && @rect
+
+        text = @format.call(remaining).to_s[0, @rect.width]
+        window.setpos(@rect.y, @rect.x)
+        window.attron(theme[:warning]) { window.addstr(text) }
+      end
+    end
+  end
+end

data/lib/potty/widgets/flash_message.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Potty
+  module Widgets
+    # Temporary notification message
+    class FlashMessage < Base
+      attr_reader :message, :type
+
+      def initialize(app)
+        super
+        @message = nil
+        @type = :info
+        @timeout = nil
+      end
+
+      def show(message, type: :info, timeout: 5)
+        @message = message
+        @type = type
+        @timeout = Time.now + timeout if timeout
+      end
+
+      def clear
+        @message = nil
+        @timeout = nil
+      end
+
+      def preferred_height(width)
+        1
+      end
+
+      def render(window)
+        return unless @rect
+
+        # Auto-clear if timed out
+        if @message && @timeout && Time.now > @timeout
+          clear
+        end
+
+        # Clear the line first
+        window.setpos(@rect.y, @rect.x)
+        window.addstr(" " * @rect.width)
+
+        # Show message if present
+        if @message
+          attr = case @type
+                 when :success then theme[:success]
+                 when :error then theme[:error]
+                 when :warning then theme[:warning]
+                 else theme[:info]
+                 end
+
+          window.setpos(@rect.y, @rect.x)
+          window.attron(attr) do
+            prefix = case @type
+                     when :success then "\u2713 "
+                     when :error then "\u2717 "
+                     when :warning then "\u26A0 "
+                     else "\u2139 "
+                     end
+            text = "#{prefix}#{@message}"[0, @rect.width]
+            window.addstr(text)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/potty/widgets/label.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Potty
+  module Widgets
+    # Static, non-focusable text — form field labels, headings, captions.
+    # Single line, truncated to the rect width. Color is a theme name;
+    # `bold:` ORs in A_BOLD via the theme.
+    class Label < Base
+      attr_accessor :text, :color, :bold
+
+      def initialize(app, text: '', color: :normal, bold: false)
+        super(app)
+        @text = text
+        @color = color
+        @bold = bold
+      end
+
+      def can_focus?
+        false
+      end
+
+      def preferred_height(_width)
+        1
+      end
+
+      def render(window)
+        return unless @visible && @rect
+
+        attr = @bold ? theme.attr(@color, bold: true) : theme[@color]
+        window.setpos(@rect.y, @rect.x)
+        window.attron(attr) { window.addstr(@text.to_s[0, @rect.width] || '') }
+      end
+    end
+  end
+end

data/lib/potty/widgets/list.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'list_item'
+require_relative '../keys'
+require_relative '../border'
+
+module Potty
+  module Widgets
+    # Scrollable list widget with heterogeneous items.
+    # Emits :select(item) on cursor move and :activate(item) on Enter.
+    class List < Base
+      attr_reader :items
+      attr_accessor :on_select, :on_activate
+
+      def initialize(app)
+        super
+        @items = []
+        @selected_index = 0
+        @scroll_offset = 0
+        @on_select = nil
+        @on_activate = nil
+      end
+
+      # Replacing the items resets the cursor to the first *selectable*
+      # item (skipping leading separators/disabled rows) so the initial
+      # highlight never lands on something you can't select.
+      def items=(list)
+        @items = list || []
+        @selected_index = first_selectable_index
+        @scroll_offset = 0
+      end
+
+      # The currently highlighted item (nil if the list is empty).
+      def selected_item
+        @items[@selected_index]
+      end
+
+      def can_focus?
+        true
+      end
+
+      def preferred_height(width)
+        [@items.size + 2, 10].max  # Items + borders, minimum 10
+      end
+
+      def render(window)
+        return unless @rect
+
+        visible_height = @rect.height - 2  # Account for borders
+
+        # Draw border
+        draw_border(window)
+
+        # Show empty message if no items
+        if @items.empty?
+          window.setpos(@rect.y + 1, @rect.x + 2)
+          window.attron(theme[:dim]) do
+            window.addstr("No items")
+          end
+          return
+        end
+
+        # Draw visible items
+        visible_items = @items[@scroll_offset, visible_height] || []
+        visible_items.each_with_index do |item, display_idx|
+          real_idx = @scroll_offset + display_idx
+          y = @rect.y + 1 + display_idx
+          x = @rect.x + 1
+
+          render_item(window, item, real_idx, y, x)
+        end
+      end
+
+      def handle_key(ch)
+        return false if @items.empty?
+
+        case ch
+        when Keys::UP
+          move_selection(-1)
+          true
+        when Keys::DOWN
+          move_selection(1)
+          true
+        when *Keys::ENTERS
+          activate_current
+          true
+        else
+          # Delegate to current item (e.g., InputItem handles typing)
+          current_item&.handle_key(ch)
+        end
+      end
+
+      private
+
+      def draw_border(window)
+        Border.draw(window, @rect, attr: theme[:normal])
+      end
+
+      def render_item(window, item, index, y, x)
+        is_selected = (index == @selected_index)
+        is_disabled = item.disabled?
+        max_width = @rect.width - 3
+
+        window.setpos(y, x)
+
+        # Selection prefix
+        prefix_attr = is_selected && @focused ? theme.attr(:selected, bold: true) : theme[:normal]
+        window.attron(prefix_attr) do
+          prefix = is_selected ? "\u2192 " : "  "
+          window.addstr(prefix)
+        end
+
+        # Try custom rendering first
+        if item.render_custom(window, theme, max_width - 2)
+          return  # Item handled its own rendering
+        end
+
+        # Default single-color rendering
+        attr = if is_selected && @focused
+                 theme.attr(:selected, bold: true)
+               elsif is_disabled
+                 theme[:dim]
+               elsif item.color
+                 theme[item.color]
+               else
+                 theme[:normal]
+               end
+
+        window.attron(attr) do
+          text = item.display_text
+          window.addstr(text[0, max_width - 2])
+        end
+      end
+
+      def move_selection(delta)
+        return if @items.empty?
+
+        # Find next enabled item
+        attempts = 0
+        new_index = @selected_index
+
+        loop do
+          new_index = (new_index + delta) % @items.size
+          break if !@items[new_index].disabled? || attempts >= @items.size
+          attempts += 1
+        end
+
+        @selected_index = new_index
+        adjust_scroll
+        @on_select&.call(@items[@selected_index])
+        emit(:select, @items[@selected_index])
+      end
+
+      def adjust_scroll
+        return unless @rect # keys can arrive before the first layout
+
+        visible_height = @rect.height - 2
+
+        # Scroll down if needed
+        if @selected_index >= @scroll_offset + visible_height
+          @scroll_offset = @selected_index - visible_height + 1
+        end
+
+        # Scroll up if needed
+        if @selected_index < @scroll_offset
+          @scroll_offset = @selected_index
+        end
+      end
+
+      def activate_current
+        return if @items.empty?
+
+        item = @items[@selected_index]
+        return if item.disabled?
+
+        @on_activate&.call(item)
+        emit(:activate, item)
+        item.activate
+      end
+
+      def current_item
+        @items[@selected_index] if @selected_index < @items.size
+      end
+
+      # First non-disabled index, or 0 if there is no selectable item.
+      def first_selectable_index
+        @items.index { |item| !item.disabled? } || 0
+      end
+    end
+  end
+end

data/lib/potty/widgets/list_item.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'curses'
+require_relative '../keys'
+
+module Potty
+  module Widgets
+    # Base list item
+    class ListItem
+      attr_reader :text, :value
+      attr_accessor :color
+
+      def initialize(text, value: nil, color: nil)
+        @text = text
+        @value = value
+        @color = color
+      end
+
+      def display_text
+        @text
+      end
+
+      # Override this to render with multiple colors
+      # Should call window.addstr() for each segment with different colors
+      # Return true if custom rendering was done, false to use default
+      def render_custom(window, theme, max_width)
+        false
+      end
+
+      def disabled?
+        false
+      end
+
+      def activate
+        # Override in subclasses
+      end
+
+      def handle_key(ch)
+        false
+      end
+    end
+
+    # Action item - executes callback when activated
+    class ActionItem < ListItem
+      def initialize(text, value: nil, color: nil, &action)
+        super(text, value: value, color: color)
+        @action = action
+      end
+
+      def activate
+        @action&.call(self)
+      end
+    end
+
+    # Disabled/greyed item
+    class DisabledItem < ListItem
+      def disabled?
+        true
+      end
+    end
+
+    # Text input item - allows inline text editing
+    class InputItem < ListItem
+      attr_accessor :input_value
+
+      def initialize(label, default: "", &on_submit)
+        super(label)
+        @input_value = default
+        @on_submit = on_submit
+        @cursor_pos = @input_value.length
+      end
+
+      def display_text
+        cursor = "_"
+        "#{@text}: #{@input_value}#{cursor}"
+      end
+
+      def handle_key(ch)
+        case ch
+        when *Keys::ENTERS
+          @on_submit&.call(@input_value)
+          true
+        when *Keys::BACKSPACES
+          if @cursor_pos > 0
+            @input_value[@cursor_pos - 1] = ''
+            @cursor_pos -= 1
+          end
+          true
+        when Keys::LEFT
+          @cursor_pos = [@cursor_pos - 1, 0].max
+          true
+        when Keys::RIGHT
+          @cursor_pos = [@cursor_pos + 1, @input_value.length].min
+          true
+        when Keys::SPACE..(Keys::DEL_ASCII - 1)  # Printable ASCII
+          @input_value.insert(@cursor_pos, ch.chr)
+          @cursor_pos += 1
+          true
+        else
+          false
+        end
+      end
+    end
+
+    # Separator - visual divider, not selectable
+    class SeparatorItem < ListItem
+      def initialize(text = "")
+        super(text)
+      end
+
+      def disabled?
+        true
+      end
+
+      def display_text
+        @text.empty? ? ("\u2500" * 40) : @text
+      end
+    end
+  end
+end

data/lib/potty/widgets/panel.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'container'
+require_relative '../border'
+
+module Potty
+  module Widgets
+    # A bordered, optionally titled container. Stacks its children
+    # vertically inside a one-cell border frame.
+    class Panel < Container
+      attr_accessor :title, :style, :color
+
+      def initialize(app, title: nil, style: :single, color: :normal, spacing: 0)
+        super(app, spacing: spacing)
+        @title = title
+        @style = style
+        @color = color
+      end
+
+      def preferred_height(width)
+        inner_w = [width - 2, 0].max
+        inner = if @children.empty?
+                  0
+                else
+                  @children.sum { |c| c.preferred_height(inner_w) } + @spacing * (@children.size - 1)
+                end
+        inner + 2 # top + bottom border
+      end
+
+      def layout_children
+        inner = Layout::Rect.new(
+          @rect.x + 1,
+          @rect.y + 1,
+          [@rect.width - 2, 0].max,
+          [@rect.height - 2, 0].max
+        )
+        rects = Layout.stack(inner, @children, spacing: @spacing)
+        @children.zip(rects).each { |child, rect| child.layout(rect) }
+      end
+
+      def render(window)
+        return unless @visible && @rect
+
+        Border.draw(window, @rect, style: @style, attr: theme[@color], title: @title)
+        super # render children inside the frame
+      end
+    end
+  end
+end

data/lib/potty/widgets/progress_bar.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Potty
+  module Widgets
+    # High-fidelity progress bar using Unicode block elements
+    # Provides 8x more granularity than simple filled/empty characters
+    # Pure string rendering - usable on a curses window or plain stdout
+    class ProgressBar
+      BLOCKS = [
+        ' ',
+        "\u258F",  # 1/8
+        "\u258E",  # 2/8
+        "\u258D",  # 3/8
+        "\u258C",  # 4/8
+        "\u258B",  # 5/8
+        "\u258A",  # 6/8
+        "\u2589",  # 7/8
+        "\u2588"   # Full
+      ].freeze
+
+      attr_reader :width
+
+      def initialize(width: 20)
+        @width = width
+      end
+
+      # Generate progress bar string
+      # @param progress [Float] Progress from 0.0 to 1.0
+      # @return [String] The rendered progress bar
+      def render(progress)
+        progress = [[progress, 0.0].max, 1.0].min
+
+        total_units = @width * 8
+        filled_units = (progress * total_units).round
+
+        full_blocks = filled_units / 8
+        partial_eighths = filled_units % 8
+
+        bar = BLOCKS[8] * full_blocks
+
+        if full_blocks < @width
+          bar += BLOCKS[partial_eighths]
+          bar += ' ' * (@width - full_blocks - 1)
+        end
+
+        bar
+      end
+
+      # Render with brackets
+      def render_with_brackets(progress)
+        "[#{render(progress)}]"
+      end
+    end
+  end
+end