potty 0.0.1

data/lib/potty/widgets/radio_group.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'curses'
+require_relative 'base'
+require_relative '../keys'
+
+module Potty
+  module Widgets
+    # N mutually exclusive options, one row each. Up/down move the cursor;
+    # Space/Enter selects the option under the cursor. Renders "(\u25CF) label"
+    # for the chosen option and "(\u25CB) label" for the rest.
+    #
+    # Note the two distinct positions: the *cursor* (highlight, moved by
+    # arrows) and the *selection* (the committed value). They diverge while
+    # the user is navigating and reconverge on select.
+    class RadioGroup < Base
+      attr_accessor :on_change
+
+      def initialize(app, options: [], selected: nil, on_change: nil)
+        super(app)
+        @options = normalize(options)
+        @on_change = on_change
+        @selected = selected.nil? ? @options.first&.fetch(:value) : selected
+        @cursor = index_of(@selected) || 0
+      end
+
+      def can_focus?
+        true
+      end
+
+      def options
+        @options
+      end
+
+      def options=(opts)
+        @options = normalize(opts)
+        @cursor = @cursor.clamp(0, [@options.size - 1, 0].max)
+      end
+
+      def selected
+        @selected
+      end
+
+      def selected=(value)
+        idx = index_of(value)
+        return unless idx
+
+        @selected = value
+        @cursor = idx
+        @on_change&.call(@selected)
+        emit(:change, @selected)
+      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
+          choose(@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
+
+          marker = opt[:value] == @selected ? "(\u25CF)" : "(\u25CB)"
+          on_cursor = @focused && i == @cursor
+          attr = on_cursor ? theme.attr(:selected, bold: true) : theme[:normal]
+          text = "#{marker} #{opt[:label]}"[0, @rect.width]
+
+          window.setpos(@rect.y + i, @rect.x)
+          window.attron(attr) { window.addstr(text) }
+        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 choose(idx)
+        opt = @options[idx]
+        return unless opt
+        return if opt[:value] == @selected
+
+        @selected = opt[:value]
+        @on_change&.call(@selected)
+        emit(:change, @selected)
+      end
+
+      def index_of(value)
+        @options.index { |o| o[:value] == value }
+      end
+    end
+  end
+end

data/lib/potty/widgets/spinner.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../animator'
+require_relative '../sprites/sample'
+
+module Potty
+  module Widgets
+    # Single-line activity indicator: an animated braille spinner, a live
+    # mutable label, and a trailing state. While active the glyph is the
+    # spinner; complete!(result) freezes it to a fixed glyph and flips the
+    # color. Passive (no focus/input). Tick-driven via an internal Animator.
+    #
+    #   s = Spinner.new(app, label: "daemon - running")
+    #   s.label = "daemon - surrendering 16 children"   # live update
+    #   s.complete!(:success)   # glyph -> checkmark, color -> :success
+    class Spinner < Base
+      STATE_GLYPHS = { success: "\u2713", failure: "\u2717", cancelled: "\u23F9" }.freeze
+      STATE_COLORS = { success: :success, failure: :error, cancelled: :dim }.freeze
+
+      attr_accessor :label, :prefix
+      attr_reader :state, :color
+
+      def initialize(app, label: '', color: :info, prefix: '  ')
+        super(app)
+        @label = label
+        @color = color
+        @prefix = prefix
+        @state = :active
+        @animator = Animator.new(app)
+        @animator << Sprites::Sample.spinner
+      end
+
+      def active?
+        @state == :active
+      end
+
+      # Freeze the spinner to a terminal state. Idempotent: only the first
+      # call takes effect, so repeated lifecycle events are harmless.
+      def complete!(result = :success)
+        return self unless active?
+
+        @state = result
+        @color = STATE_COLORS.fetch(result, @color)
+        @animator.stop
+        emit(:complete, result)
+        self
+      end
+
+      def preferred_height(_width)
+        1
+      end
+
+      def tick(now)
+        @animator.tick(now) if active?
+      end
+
+      def render(window)
+        return unless @visible && @rect
+
+        glyph = active? ? current_frame : STATE_GLYPHS.fetch(@state, '?')
+        text = truncate("#{@prefix}#{glyph} #{@label}", @rect.width)
+        window.setpos(@rect.y, @rect.x)
+        # theme.style (not theme[]) so we render in colour on either surface —
+        # curses resolves the Style to a pair, inline to ANSI SGR.
+        window.attron(theme.style(@color)) { window.addstr(text) }
+      end
+
+      private
+
+      def current_frame
+        sprite = @animator.sprite
+        sprite ? sprite.frame_lines(@animator.frame_index).first : ' '
+      end
+
+      def truncate(str, width)
+        return str if str.length <= width
+        return str[0, width] || '' if width < 2
+
+        "#{str[0, width - 1]}\u2026"
+      end
+    end
+  end
+end

data/lib/potty/widgets/status_bar.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Potty
+  module Widgets
+    # Status bar at bottom of screen
+    class StatusBar < Base
+      attr_accessor :left_text, :center_text, :right_text
+
+      def initialize(app)
+        super
+        @left_text = ""
+        @center_text = ""
+        @right_text = ""
+      end
+
+      def preferred_height(width)
+        1
+      end
+
+      def render(window)
+        return unless @rect
+
+        window.setpos(@rect.y, @rect.x)
+        window.attron(theme[:status]) do
+          # Clear line with background color
+          window.addstr(" " * @rect.width)
+
+          # Left-aligned
+          if @left_text && !@left_text.empty?
+            window.setpos(@rect.y, @rect.x)
+            max_left = @rect.width / 3
+            window.addstr(@left_text[0, max_left])
+          end
+
+          # Center-aligned
+          if @center_text && !@center_text.empty?
+            center_x = @rect.x + (@rect.width - @center_text.length) / 2
+            center_x = [center_x, @rect.x].max
+            window.setpos(@rect.y, center_x)
+            window.addstr(@center_text[0, @rect.width])
+          end
+
+          # Right-aligned
+          if @right_text && !@right_text.empty?
+            right_x = @rect.x + @rect.width - @right_text.length
+            right_x = [right_x, @rect.x].max
+            window.setpos(@rect.y, right_x)
+            window.addstr(@right_text)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/potty/widgets/text_input.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'curses'
+require_relative 'base'
+require_relative '../keys'
+
+module Potty
+  module Widgets
+    # Single-line editable text field. Shows a block cursor when focused,
+    # a dim placeholder when empty and unfocused, and scrolls horizontally
+    # when the text outgrows the field.
+    #
+    # Emits :change(text) on every edit. ASCII input only for now (matches
+    # the rest of the framework); UTF-8 entry would need multibyte getch.
+    class TextInput < Base
+      attr_reader :text
+      attr_accessor :placeholder, :max_length, :on_change
+
+      def initialize(app, text: '', placeholder: '', max_length: nil, on_change: nil)
+        super(app)
+        @text = text.dup
+        @placeholder = placeholder
+        @max_length = max_length
+        @on_change = on_change
+        @cursor = @text.length
+        @scroll = 0
+      end
+
+      def can_focus?
+        true
+      end
+
+      def text=(value)
+        @text = value.to_s.dup
+        @cursor = [@cursor, @text.length].min
+        notify_change
+      end
+
+      def preferred_height(_width)
+        1
+      end
+
+      def handle_key(ch)
+        case ch
+        when Keys::LEFT
+          @cursor = [@cursor - 1, 0].max
+        when Keys::RIGHT
+          @cursor = [@cursor + 1, @text.length].min
+        when Keys::HOME, Keys::CTRL_A
+          @cursor = 0
+        when Keys::END_, Keys::CTRL_E
+          @cursor = @text.length
+        when Keys::DEL_ASCII, Keys::CTRL_H, Keys::BACKSPACE
+          backspace
+        when Keys::DELETE, Keys::CTRL_D
+          delete_forward
+        when Keys::SPACE..(Keys::DEL_ASCII - 1)
+          insert(ch.chr)
+        else
+          return false
+        end
+        true
+      end
+
+      def render(window)
+        return unless @visible && @rect
+
+        width = @rect.width
+        adjust_scroll(width)
+
+        if @text.empty? && !@focused
+          window.setpos(@rect.y, @rect.x)
+          window.attron(theme[:dim]) do
+            window.addstr(@placeholder.to_s[0, width].to_s.ljust(width))
+          end
+          return
+        end
+
+        visible = (@text[@scroll, width] || '').ljust(width)
+        window.setpos(@rect.y, @rect.x)
+        window.attron(theme[:normal]) { window.addstr(visible) }
+
+        return unless @focused
+
+        # Block cursor: reverse-video the cell under the caret.
+        col = @cursor - @scroll
+        return if col.negative? || col >= width
+
+        char_under = @text[@cursor] || ' '
+        window.setpos(@rect.y, @rect.x + col)
+        window.attron(theme[:normal] | ::Curses::A_REVERSE) do
+          window.addstr(char_under)
+        end
+      end
+
+      private
+
+      def insert(str)
+        return if @max_length && @text.length >= @max_length
+
+        @text.insert(@cursor, str)
+        @cursor += str.length
+        notify_change
+      end
+
+      def backspace
+        return if @cursor.zero?
+
+        @text.slice!(@cursor - 1)
+        @cursor -= 1
+        notify_change
+      end
+
+      def delete_forward
+        return if @cursor >= @text.length
+
+        @text.slice!(@cursor)
+        notify_change
+      end
+
+      def adjust_scroll(width)
+        return if width <= 0
+
+        @scroll = @cursor - width + 1 if @cursor - @scroll >= width
+        @scroll = @cursor if @cursor < @scroll
+        @scroll = [@scroll, 0].max
+      end
+
+      def notify_change
+        # Hand listeners a snapshot, not the live internal buffer, so a
+        # consumer that stores the value doesn't see it mutate underfoot.
+        snapshot = @text.dup
+        @on_change&.call(snapshot)
+        emit(:change, snapshot)
+      end
+    end
+  end
+end

data/lib/potty/widgets/toggle.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../keys'
+
+module Potty
+  module Widgets
+    # Boolean on/off control. Space (or Enter) flips it when focused.
+    # Renders "[\u25CF] label" when on, "[\u25CB] label" when off.
+    # Emits :change(value) when toggled.
+    class Toggle < Base
+      attr_reader :value
+      attr_accessor :label, :on_change
+
+      def initialize(app, label: '', value: false, on_change: nil)
+        super(app)
+        @label = label
+        @value = value
+        @on_change = on_change
+      end
+
+      def can_focus?
+        true
+      end
+
+      def value=(val)
+        val = val ? true : false
+        return if val == @value
+
+        @value = val
+        @on_change&.call(@value)
+        emit(:change, @value)
+      end
+
+      def toggle
+        self.value = !@value
+      end
+
+      def preferred_height(_width)
+        1
+      end
+
+      def handle_key(ch)
+        case ch
+        when Keys::SPACE, *Keys::ENTERS
+          toggle
+          true
+        else
+          false
+        end
+      end
+
+      def render(window)
+        return unless @visible && @rect
+
+        knob = @value ? "[\u25CF]" : "[\u25CB]"
+        text = "#{knob} #{@label}"[0, @rect.width]
+        attr = @focused ? theme.attr(:selected, bold: true) : theme[:normal]
+
+        window.setpos(@rect.y, @rect.x)
+        window.attron(attr) { window.addstr(text) }
+      end
+    end
+  end
+end

data/lib/potty/window_manager.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'curses'
+
+module Potty
+  # Manages curses window lifecycle and refresh coordination
+  class WindowManager
+    attr_reader :stdscr, :max_y, :max_x
+
+    def initialize
+      @windows = {}
+      @stdscr = nil
+    end
+
+    # Called during application setup
+    def setup(stdscr)
+      @stdscr = stdscr
+      update_dimensions
+    end
+
+    def update_dimensions
+      @max_y, @max_x = @stdscr.maxy, @stdscr.maxx
+    end
+
+    # Create a new window
+    def create_window(name, height, width, y, x)
+      win = ::Curses::Window.new(height, width, y, x)
+      @windows[name] = win
+      win
+    end
+
+    # Get existing window
+    def get_window(name)
+      @windows[name]
+    end
+
+    # Destroy window
+    def destroy_window(name)
+      @windows[name]&.close
+      @windows.delete(name)
+    end
+
+    # Refresh all windows efficiently
+    def refresh_all
+      @stdscr.noutrefresh
+      @windows.values.each(&:noutrefresh)
+      ::Curses.doupdate
+    end
+
+    def clear_all
+      @stdscr.clear
+      @windows.values.each(&:clear)
+    end
+  end
+end

data/lib/potty.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'potty/version'
+require_relative 'potty/keys'
+require_relative 'potty/events'
+require_relative 'potty/style'
+require_relative 'potty/application'
+require_relative 'potty/theme'
+require_relative 'potty/layout'
+require_relative 'potty/border'
+require_relative 'potty/window_manager'
+require_relative 'potty/view'
+require_relative 'potty/widgets/base'
+require_relative 'potty/widgets/container'
+require_relative 'potty/widgets/panel'
+require_relative 'potty/widgets/list'
+require_relative 'potty/widgets/list_item'
+require_relative 'potty/widgets/colored_fields_item'
+require_relative 'potty/widgets/flash_message'
+require_relative 'potty/widgets/status_bar'
+require_relative 'potty/widgets/progress_bar'
+require_relative 'potty/widgets/label'
+require_relative 'potty/widgets/button'
+require_relative 'potty/widgets/text_input'
+require_relative 'potty/widgets/toggle'
+require_relative 'potty/widgets/radio_group'
+require_relative 'potty/widgets/checkbox_group'
+require_relative 'potty/widgets/countdown'
+require_relative 'potty/widgets/spinner'
+require_relative 'potty/sprite'
+require_relative 'potty/animator'
+require_relative 'potty/sprites/sample'
+
+module Potty
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: potty
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- TwilightCoders
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: curses
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: Provides views, widgets, layout, theming, and frame-based animation for
+  building curses TUI applications.
+email:
+- info@twilightcoders.net
+executables:
+- potty_demo
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- bin/potty_demo
+- examples/test_view.rb
+- lib/potty.rb
+- lib/potty/animator.rb
+- lib/potty/application.rb
+- lib/potty/border.rb
+- lib/potty/events.rb
+- lib/potty/keys.rb
+- lib/potty/layout.rb
+- lib/potty/sprite.rb
+- lib/potty/sprites/sample.rb
+- lib/potty/style.rb
+- lib/potty/surface.rb
+- lib/potty/surfaces/curses_surface.rb
+- lib/potty/surfaces/inline_surface.rb
+- lib/potty/theme.rb
+- lib/potty/version.rb
+- lib/potty/view.rb
+- lib/potty/widgets/base.rb
+- lib/potty/widgets/button.rb
+- lib/potty/widgets/checkbox_group.rb
+- lib/potty/widgets/colored_fields_item.rb
+- lib/potty/widgets/container.rb
+- lib/potty/widgets/countdown.rb
+- lib/potty/widgets/flash_message.rb
+- lib/potty/widgets/label.rb
+- lib/potty/widgets/list.rb
+- lib/potty/widgets/list_item.rb
+- lib/potty/widgets/panel.rb
+- lib/potty/widgets/progress_bar.rb
+- lib/potty/widgets/radio_group.rb
+- lib/potty/widgets/spinner.rb
+- lib/potty/widgets/status_bar.rb
+- lib/potty/widgets/text_input.rb
+- lib/potty/widgets/toggle.rb
+- lib/potty/window_manager.rb
+homepage: https://github.com/TwilightCoders/potty
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/TwilightCoders/potty
+  changelog_uri: https://github.com/TwilightCoders/potty/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A curses-based terminal UI framework for Ruby
+test_files: []