charming 0.1.1 → 0.1.3

data/lib/charming/presentation/components/spinner.rb

@@ -1,38 +1,46 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class Spinner < Component
-        DEFAULT_FRAMES = ["-", "\\", "|", "/"].freeze
-
-        attr_reader :frames, :index, :label
-
-        def initialize(frames: DEFAULT_FRAMES, index: 0, label: nil)
-          super()
-          raise ArgumentError, "frames cannot be empty" if frames.empty?
-
-          @frames = frames
-          @index = index
-          @label = label
-        end
+  module Components
+    # Spinner is a simple rotating-frame indicator. The component cycles through a list of
+    # frames on each `tick`; pair it with a controller timer to drive animation. An optional
+    # *label* is appended after the current frame on each render.
+    class Spinner < Component
+      # The default frame set: a 4-frame ASCII spinner.
+      DEFAULT_FRAMES = ["-", "\\", "|", "/"].freeze
+
+      # The current frame list, frame index, and optional label string.
+      attr_reader :frames, :index, :label
+
+      # *frames* defaults to DEFAULT_FRAMES but may be replaced with any array of frame strings.
+      # *index* is the starting frame index. *label* is an optional suffix shown after the frame.
+      def initialize(frames: DEFAULT_FRAMES, index: 0, label: nil)
+        super()
+        raise ArgumentError, "frames cannot be empty" if frames.empty?
+
+        @frames = frames
+        @index = index
+        @label = label
+      end
 
-        def tick
-          @index = (index + 1) % frames.length
-          self
-        end
+      # Advances the frame index by one position, wrapping around. Returns self for chaining.
+      def tick
+        @index = (index + 1) % frames.length
+        self
+      end
 
-        def render
-          return frame unless label
+      # Renders the current frame, optionally followed by the label and a space.
+      def render
+        return frame unless label
 
-          "#{frame} #{label}"
-        end
+        "#{frame} #{label}"
+      end
 
-        private
+      private
 
-        def frame
-          frames.fetch(index % frames.length)
-        end
+      # Returns the current frame string (with index modulo frame count to be safe).
+      def frame
+        frames.fetch(index % frames.length)
       end
     end
   end

data/lib/charming/presentation/components/table.rb

@@ -3,115 +3,138 @@
 require "tty-table"
 
 module Charming
-  module Presentation
-    module Components
-      class Table < Component
-        include KeyboardHandler
-
-        KEY_ACTIONS = {
-          up: :move_up,
-          down: :move_down,
-          home: :move_home,
-          end: :move_end
-        }.freeze
-
-        HEADER_HEIGHT = 2
-
-        attr_reader :header, :rows, :selected_index
-
-        def initialize(header:, rows: [], selected_index: 0, keymap: :vim)
-          super()
-          @header = Array(header).map(&:to_s)
-          @rows = Array(rows)
-          @selected_index = clamp_index(selected_index)
-          @keymap = keymap
-        end
+  module Components
+    # Table renders tabular data with a header row, a selected row highlight, and keyboard
+    # navigation. Mouse clicks within the body area also select rows. The table is rendered
+    # via tty-table and the selected row is overlaid with reverse-video ANSI styling.
+    class Table < Component
+      include KeyboardHandler
+
+      # Maps navigation keys to the instance methods that move the selection. Shared with
+      # List and Viewport via KeyboardHandler.
+      KEY_ACTIONS = {
+        up: :move_up,
+        down: :move_down,
+        home: :move_home,
+        end: :move_end
+      }.freeze
+
+      # Number of terminal rows occupied by the table's top border and header line. Used by
+      # the mouse handler to translate absolute row coordinates to body rows.
+      HEADER_HEIGHT = 2
+
+      # The header row, the body rows, and the currently selected row index, respectively.
+      attr_reader :header, :rows, :selected_index
+
+      # *header* is an array of column labels. *rows* is the array of body rows (each either a
+      # String, an Array, or a Hash of column-value pairs). *selected_index* defaults to 0.
+      # *keymap* selects the keybinding style (`:vim` enables h/j/k/l → left/down/up/right).
+      def initialize(header:, rows: [], selected_index: 0, keymap: :vim)
+        super()
+        @header = Array(header).map(&:to_s)
+        @rows = Array(rows)
+        @selected_index = clamp_index(selected_index)
+        @keymap = keymap
+      end
 
-        def handle_key(event)
-          return nil if rows.empty?
+      # Handles key events. Returns `[:selected, row]` on Enter; otherwise delegates to the
+      # KeyboardHandler for navigation keys.
+      def handle_key(event)
+        return nil if rows.empty?
 
-          case Charming.key_of(event)
-          when :enter then [:selected, selected_row]
-          else super
-          end
+        case Charming.key_of(event)
+        when :enter then [:selected, selected_row]
+        else super
         end
+      end
 
-        def handle_mouse(event)
-          return nil if rows.empty?
-          return nil unless event.respond_to?(:click?) && event.click?
-
-          clicked = event.y - HEADER_HEIGHT
-          return nil if clicked.negative? || clicked >= rows.length
+      # Handles mouse events: a click within the body area selects the clicked row.
+      # Returns :handled on a successful click.
+      def handle_mouse(event)
+        return nil if rows.empty?
+        return nil unless event.respond_to?(:click?) && event.click?
 
-          @selected_index = clicked
-          :handled
-        end
+        clicked = event.y - HEADER_HEIGHT
+        return nil if clicked.negative? || clicked >= rows.length
 
-        def selected_row
-          rows[selected_index]
-        end
+        @selected_index = clicked
+        :handled
+      end
 
-        def render
-          return "(empty table)" if header.empty? && rows.empty?
+      # Returns the currently selected row, or nil when the table is empty.
+      def selected_row
+        rows[selected_index]
+      end
 
-          normalized = rows.map { |row| normalize_row(row) }
-          lines = TTY::Table.new(header: header, rows: normalized)
-            .render(:unicode)
-            .lines(chomp: true)
+      # Renders the table to a string. Returns a placeholder when both header and rows are empty.
+      def render
+        return "(empty table)" if header.empty? && rows.empty?
 
-          compact_layout(lines)
-        end
+        normalized = rows.map { |row| normalize_row(row) }
+        lines = TTY::Table.new(header: header, rows: normalized)
+          .render(:unicode)
+          .lines(chomp: true)
 
-        private
+        compact_layout(lines)
+      end
 
-        def normalize_row(row)
-          cells = case row
-          when Hash then row.values
-          when String then [row]
-          else Array(row)
-          end
-          return cells if header.length <= 1 || cells.length <= header.length
+      private
 
-          kept = cells.first(header.length - 1)
-          merged = cells[(header.length - 1)..].join(" ")
-          kept + [merged]
+      # Coerces a *row* (Hash / String / Array) into a flat cell array matching the header.
+      # Excess cells are merged into the last column with a space separator.
+      def normalize_row(row)
+        cells = case row
+        when Hash then row.values
+        when String then [row]
+        else Array(row)
         end
+        return cells if header.length <= 1 || cells.length <= header.length
 
-        def compact_layout(lines)
-          return lines.join("\n") if lines.length < 4
+        kept = cells.first(header.length - 1)
+        merged = cells[(header.length - 1)..].join(" ")
+        kept + [merged]
+      end
 
-          top, header_line, _separator, *rest = lines
-          body = rest.first(rows.length)
-          bottom = rest[rows.length]
+      # Applies the selected-row highlight and trims unused body rows below the actual row count.
+      def compact_layout(lines)
+        return lines.join("\n") if lines.length < 4
 
-          highlighted = body.each_with_index.map do |line, index|
-            (index == selected_index) ? "\e[7m#{line}\e[m" : line
-          end
+        top, header_line, _separator, *rest = lines
+        body = rest.first(rows.length)
+        bottom = rest[rows.length]
 
-          [top, header_line, *highlighted, bottom].compact.join("\n")
+        highlighted = body.each_with_index.map do |line, index|
+          (index == selected_index) ? "\e[7m#{line}\e[m" : line
         end
 
-        def move_up
-          @selected_index -= 1 if selected_index.positive?
-        end
+        [top, header_line, *highlighted, bottom].compact.join("\n")
+      end
 
-        def move_down
-          @selected_index += 1 if selected_index < rows.length - 1
-        end
+      # Moves the selection up one row.
+      def move_up
+        @selected_index -= 1 if selected_index.positive?
+      end
 
-        def move_home
-          @selected_index = 0
-        end
+      # Moves the selection down one row.
+      def move_down
+        @selected_index += 1 if selected_index < rows.length - 1
+      end
 
-        def move_end
-          @selected_index = rows.length - 1
-        end
+      # Moves the selection to the first row.
+      def move_home
+        @selected_index = 0
+      end
 
-        def clamp_index(value)
-          return 0 if rows.empty?
+      # Moves the selection to the last row.
+      def move_end
+        @selected_index = rows.length - 1
+      end
 
-          value.to_i.clamp(0, rows.length - 1)
-        end
+      # Clamps *value* to the valid row range, defaulting to 0 when the table is empty.
+      def clamp_index(value)
+        return 0 if rows.empty?
+
+        value.to_i.clamp(0, rows.length - 1)
       end
     end
   end