bubbles 0.0.5 → 0.1.0

data/lib/bubbles/help.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Bubbles
+  # Help renders help text from key bindings.
+  #
+  # Example:
+  #   help = Bubbles::Help.new
+  #   help.width = 80
+  #
+  #   # Define a keymap with short_help and full_help methods
+  #   class MyKeyMap
+  #     BINDINGS = {
+  #       up: Bubbles::Key.binding(keys: ["up", "k"], help: ["↑/k", "up"]),
+  #       down: Bubbles::Key.binding(keys: ["down", "j"], help: ["↓/j", "down"]),
+  #       help: Bubbles::Key.binding(keys: ["?"], help: ["?", "help"]),
+  #       quit: Bubbles::Key.binding(keys: ["q"], help: ["q", "quit"])
+  #     }
+  #
+  #     def short_help
+  #       [BINDINGS[:help], BINDINGS[:quit]]
+  #     end
+  #
+  #     def full_help
+  #       [
+  #         [BINDINGS[:up], BINDINGS[:down]],
+  #         [BINDINGS[:help], BINDINGS[:quit]]
+  #       ]
+  #     end
+  #   end
+  #
+  #   keymap = MyKeyMap.new
+  #   puts help.view(keymap)
+  #
+  class Help
+    DEFAULT_KEY_STYLE = nil #: Lipgloss::Style?
+    DEFAULT_DESC_STYLE = nil #: Lipgloss::Style?
+    DEFAULT_SEPARATOR_STYLE = nil #: Lipgloss::Style?
+
+    attr_accessor :width #: Integer
+    attr_accessor :show_all #: bool
+    attr_accessor :short_separator #: String
+    attr_accessor :full_separator #: String
+    attr_accessor :full_help_column_gap #: Integer
+    attr_accessor :key_style #: Lipgloss::Style?
+    attr_accessor :desc_style #: Lipgloss::Style?
+    attr_accessor :separator_style #: Lipgloss::Style?
+
+    #: () -> void
+    def initialize
+      @width = 0
+      @show_all = false
+      @short_separator = " • "
+      @full_separator = "    "
+      @full_help_column_gap = 2
+      @key_style = nil
+      @desc_style = nil
+      @separator_style = nil
+    end
+
+    #: (untyped) -> String
+    def view(keymap)
+      if @show_all && keymap.respond_to?(:full_help)
+        full_help_view(keymap.full_help)
+      elsif keymap.respond_to?(:short_help)
+        short_help_view(keymap.short_help)
+      else
+        ""
+      end
+    end
+
+    #: (Array[Key::Binding]?) -> String
+    def short_help_view(bindings)
+      return "" if bindings.nil? || bindings.empty?
+
+      parts = bindings.filter_map do |binding|
+        next unless binding.is_a?(Key::Binding)
+        next unless binding.enabled? && binding.help?
+
+        render_binding(binding)
+      end
+
+      return "" if parts.empty?
+
+      separator = render_separator(@short_separator)
+      result = parts.join(separator)
+
+      truncate_to_width(result)
+    end
+
+    #: (Array[Array[Key::Binding]]?) -> String
+    def full_help_view(binding_groups)
+      return "" if binding_groups.nil? || binding_groups.empty?
+
+      columns = binding_groups.map do |group|
+        group.filter_map do |binding|
+          next unless binding.is_a?(Key::Binding)
+          next unless binding.enabled? && binding.help?
+
+          render_binding(binding)
+        end
+      end
+
+      columns.reject!(&:empty?)
+      return "" if columns.empty?
+
+      max_rows = columns.map(&:length).max
+
+      rows = (0...max_rows).map do |row_index|
+        row_parts = columns.map do |col|
+          col[row_index] || ""
+        end
+
+        row_parts.join(@full_separator)
+      end
+
+      result = rows.join("\n")
+
+      truncate_to_width(result)
+    end
+
+    private
+
+    #: (Key::Binding) -> String
+    def render_binding(binding)
+      key, desc = binding.help
+      key_rendered = render_key(key)
+      desc_rendered = render_desc(desc)
+
+      "#{key_rendered} #{desc_rendered}"
+    end
+
+    #: (String) -> String
+    def render_key(text)
+      (style = @key_style) ? style.render(text) : text
+    end
+
+    #: (String) -> String
+    def render_desc(text)
+      (style = @desc_style) ? style.render(text) : text
+    end
+
+    #: (String) -> String
+    def render_separator(text)
+      (style = @separator_style) ? style.render(text) : text
+    end
+
+    #: (String) -> String
+    def truncate_to_width(text)
+      return text if @width <= 0
+
+      lines = text.split("\n")
+
+      lines.map do |line|
+        plain = strip_ansi(line)
+
+        if plain.length > @width
+          line[0, @width]
+        else
+          line
+        end
+      end.join("\n")
+    end
+
+    #: (String) -> String
+    def strip_ansi(str)
+      str.gsub(/\e\[[0-9;]*[A-Za-z]/, "")
+    end
+  end
+end

data/lib/bubbles/key.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Bubbles
+  # Key provides helpers for defining and matching key bindings.
+  #
+  # Example:
+  #   # Define key bindings
+  #   KEYS = {
+  #     up: Bubbles::Key.binding(
+  #       keys: ["up", "k"],
+  #       help: ["↑/k", "move up"]
+  #     ),
+  #     down: Bubbles::Key.binding(
+  #       keys: ["down", "j"],
+  #       help: ["↓/j", "move down"]
+  #     ),
+  #     quit: Bubbles::Key.binding(
+  #       keys: ["q", "esc", "ctrl+c"],
+  #       help: ["q", "quit"]
+  #     )
+  #   }
+  #
+  #   # Match in update
+  #   def update(message)
+  #     case message
+  #     when Bubbletea::KeyMessage
+  #       if Bubbles::Key.matches?(message, KEYS[:up])
+  #         # handle up
+  #       elsif Bubbles::Key.matches?(message, KEYS[:down])
+  #         # handle down
+  #       end
+  #     end
+  #   end
+  #
+  module Key
+    class Binding
+      attr_accessor :keys #: Array[String]
+      attr_accessor :help_key #: String?
+      attr_accessor :help_desc #: String?
+      attr_accessor :enabled #: bool
+
+      #: (keys: Array[String], ?help_key: String?, ?help_desc: String?, ?enabled: bool) -> void
+      def initialize(keys:, help_key: nil, help_desc: nil, enabled: true)
+        @keys = Array(keys)
+        @help_key = help_key
+        @help_desc = help_desc
+        @enabled = enabled
+      end
+
+      #: () -> bool
+      def enabled?
+        @enabled
+      end
+
+      #: () -> bool
+      def help?
+        !!((key = @help_key) && !key.empty? && (desc = @help_desc) && !desc.empty?)
+      end
+
+      #: () -> [String, String]
+      def help
+        [@help_key || "", @help_desc || ""]
+      end
+    end
+
+    class << self
+      #: (keys: Array[String] | String, ?help: Array[String]?, ?enabled: bool) -> Binding
+      def binding(keys:, help: nil, enabled: true)
+        help_key, help_desc = help || [nil, nil]
+        keys_array = keys.is_a?(Array) ? keys : [keys] #: Array[String]
+
+        Binding.new(
+          keys: keys_array,
+          help_key: help_key,
+          help_desc: help_desc,
+          enabled: enabled
+        )
+      end
+
+      #: (Bubbletea::KeyMessage, *Binding) -> bool
+      def matches?(message, *bindings)
+        return false unless message.is_a?(Bubbletea::KeyMessage)
+
+        key_string = message.to_s
+
+        bindings.flatten.any? do |binding|
+          next false unless binding.is_a?(Binding)
+          next false unless binding.enabled?
+
+          binding.keys.any? { |k| k == key_string }
+        end
+      end
+    end
+  end
+end

data/lib/bubbles/list.rb

@@ -0,0 +1,365 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Bubbles
+  # List is a feature-rich component for browsing a list of items.
+  # It features optional filtering, pagination, and status messages.
+  #
+  # Example:
+  #   items = [
+  #     { title: "Item 1", description: "Description 1" },
+  #     { title: "Item 2", description: "Description 2" }
+  #   ]
+  #   list = Bubbles::List.new(items, width: 40, height: 10)
+  #
+  #   # In update:
+  #   list, command = list.update(message)
+  #
+  #   # In view:
+  #   list.view
+  #
+  class List
+    UNFILTERED = :unfiltered #: Symbol
+    FILTERING = :filtering #: Symbol
+    FILTER_APPLIED = :filter_applied #: Symbol
+
+    class StatusMessageTimeoutMessage < Bubbletea::Message
+    end
+
+    attr_accessor :width #: Integer
+    attr_accessor :height #: Integer
+    attr_accessor :title #: String
+    attr_accessor :show_title #: bool
+    attr_accessor :show_filter #: bool
+    attr_accessor :show_pagination #: bool
+    attr_accessor :show_status_bar #: bool
+    attr_accessor :status_message_lifetime #: Float
+    attr_accessor :fill_height #: bool
+    attr_accessor :title_style #: Lipgloss::Style?
+    attr_accessor :item_style #: Lipgloss::Style?
+    attr_accessor :selected_item_style #: Lipgloss::Style?
+    attr_accessor :filter_prompt #: String
+    attr_accessor :filter_style #: Lipgloss::Style?
+    attr_accessor :status_bar_style #: Lipgloss::Style?
+    attr_accessor :pagination_style #: Lipgloss::Style?
+
+    attr_reader :filter_state #: Symbol
+    attr_reader :filter_input #: TextInput
+
+    #: (?Array[untyped], ?width: Integer, ?height: Integer) -> void
+    def initialize(items = [], width: 40, height: 10)
+      @width = width
+      @height = height
+
+      @items = items
+      @filtered_items = items.dup
+      @selected = 0
+      @offset = 0
+
+      @title = "List"
+      @show_title = true
+      @show_filter = true
+      @show_pagination = true
+      @show_status_bar = true
+      @fill_height = true
+
+      @filter_state = UNFILTERED
+      @filter_input = TextInput.new
+      @filter_input.prompt = "Filter: "
+      @filter_prompt = "/"
+
+      @paginator = Paginator.new(type: Paginator::DOTS)
+      @status_message = ""
+      @status_message_lifetime = 1.0
+
+      @title_style = nil
+      @item_style = nil
+      @selected_item_style = nil
+      @filter_style = nil
+      @status_bar_style = nil
+      @pagination_style = nil
+
+      update_pagination
+    end
+
+    #: (Array[untyped]) -> void
+    def items=(items)
+      @items = items
+      reset_filter
+    end
+
+    attr_reader :items #: Array[untyped]
+
+    #: () -> Array[untyped]
+    def visible_items
+      @filtered_items
+    end
+
+    #: () -> Integer
+    def selected_index
+      @selected
+    end
+
+    #: () -> untyped
+    def selected_item
+      @filtered_items[@selected]
+    end
+
+    #: (Integer) -> void
+    def select(index)
+      @selected = index.clamp(0, [@filtered_items.length - 1, 0].max)
+      update_offset
+    end
+
+    #: () -> void
+    def select_next
+      select(@selected + 1)
+    end
+
+    #: () -> void
+    def select_prev
+      select(@selected - 1)
+    end
+
+    #: (String) -> Bubbletea::Command
+    def set_status_message(message) # rubocop:disable Naming/AccessorMethodName
+      @status_message = message
+      Bubbletea.tick(@status_message_lifetime) { StatusMessageTimeoutMessage.new }
+    end
+
+    #: () -> void
+    def clear_status_message
+      @status_message = ""
+    end
+
+    #: () -> Bubbletea::Command?
+    def start_filtering
+      @filter_state = FILTERING
+      @filter_input.focus
+    end
+
+    #: () -> void
+    def apply_filter
+      return if @filter_state != FILTERING
+
+      if @filter_input.value.empty?
+        reset_filter
+      else
+        @filter_state = FILTER_APPLIED
+        @filter_input.blur
+
+        do_filter
+      end
+    end
+
+    #: () -> void
+    def reset_filter
+      @filter_state = UNFILTERED
+      @filter_input.reset
+      @filter_input.blur
+      @filtered_items = @items.dup
+      @selected = 0
+
+      update_pagination
+    end
+
+    #: (Bubbletea::Message) -> [List, Bubbletea::Command?]
+    def update(message)
+      commands = [] #: Array[Bubbletea::Command]
+
+      case message
+      when StatusMessageTimeoutMessage
+        clear_status_message
+
+        return [self, nil]
+      when Bubbletea::KeyMessage
+        if @filter_state == FILTERING
+          case message.to_s
+          when "enter"
+            apply_filter
+          when "esc"
+            reset_filter
+          else
+            @filter_input, command = @filter_input.update(message)
+            commands << command if command
+
+            do_filter
+          end
+        else
+          case message.to_s
+          when "up", "k"
+            select_prev
+          when "down", "j"
+            select_next
+          when "home", "g"
+            select(0)
+          when "end", "G"
+            select(@filtered_items.length - 1)
+          when "pgup", "ctrl+b"
+            select(@selected - visible_item_count)
+          when "pgdown", "ctrl+f"
+            select(@selected + visible_item_count)
+          when "/"
+            return [self, start_filtering] if @show_filter
+          when "esc"
+            reset_filter if @filter_state == FILTER_APPLIED
+          end
+        end
+      end
+
+      update_pagination
+
+      [self, commands.empty? ? nil : Bubbletea.batch(*commands)]
+    end
+
+    #: () -> String
+    def view
+      sections = [] #: Array[String]
+
+      if @show_title
+        title = (style = @title_style) ? style.render(@title) : @title
+        sections << title
+        sections << ""
+      end
+
+      if @show_filter && @filter_state != UNFILTERED
+        sections << @filter_input.view
+        sections << ""
+      end
+
+      sections << items_view
+
+      if @show_pagination && @filtered_items.length > visible_item_count
+        sections << ""
+        pagination = @paginator.view
+        sections << ((style = @pagination_style) ? style.render(pagination) : pagination)
+      end
+
+      if @show_status_bar && !@status_message.empty?
+        sections << ""
+        status = (style = @status_bar_style) ? style.render(@status_message) : @status_message
+        sections << status
+      end
+
+      sections.join("\n")
+    end
+
+    private
+
+    #: () -> String
+    def items_view
+      return "No items" if @filtered_items.empty?
+
+      lines = [] #: Array[String]
+      end_index = [@offset + visible_item_count, @filtered_items.length].min
+
+      (@offset...end_index).each do |i|
+        item = @filtered_items[i]
+        is_selected = i == @selected
+
+        line = render_item(item, i, is_selected)
+        lines << line
+      end
+
+      (lines << "" while lines.length < visible_item_count) if @fill_height
+
+      lines.join("\n")
+    end
+
+    #: (untyped, Integer, bool) -> String
+    def render_item(item, _index, selected)
+      text = item_title(item)
+
+      if selected
+        prefix = "> "
+        if (style = @selected_item_style)
+          style.render(prefix + text)
+        else
+          "\e[7m#{prefix}#{text}\e[0m"
+        end
+      else
+        prefix = "  "
+        if (style = @item_style)
+          style.render(prefix + text)
+        else
+          prefix + text
+        end
+      end
+    end
+
+    #: (untyped) -> String
+    def item_title(item)
+      if item.respond_to?(:title)
+        item.title
+      elsif item.is_a?(Hash) && item[:title]
+        item[:title]
+      elsif item.respond_to?(:filter_value)
+        item.filter_value
+      else
+        item.to_s
+      end
+    end
+
+    #: (untyped) -> String
+    def item_filter_value(item)
+      if item.respond_to?(:filter_value)
+        item.filter_value
+      elsif item.respond_to?(:title)
+        item.title
+      elsif item.is_a?(Hash) && item[:title]
+        item[:title]
+      else
+        item.to_s
+      end
+    end
+
+    #: () -> void
+    def do_filter
+      query = @filter_input.value.downcase
+
+      @filtered_items = if query.empty?
+                          @items.dup
+                        else
+                          @items.select do |item|
+                            item_filter_value(item).downcase.include?(query)
+                          end
+                        end
+
+      @selected = 0 if @selected >= @filtered_items.length
+      update_offset
+      update_pagination
+    end
+
+    #: () -> Integer
+    def visible_item_count
+      overhead = 0
+
+      overhead += 2 if @show_title # Title + blank line
+      overhead += 2 if @show_filter && @filter_state != UNFILTERED # Filter + blank line
+      overhead += 2 if @show_pagination && @filtered_items.length > @height - overhead
+      overhead += 2 if @show_status_bar && !@status_message.empty?
+
+      [@height - overhead, 1].max
+    end
+
+    #: () -> void
+    def update_offset
+      visible = visible_item_count
+
+      if @selected < @offset
+        @offset = @selected
+      elsif @selected >= @offset + visible
+        @offset = @selected - visible + 1
+      end
+
+      @offset = @offset.clamp(0, [@filtered_items.length - visible, 0].max)
+    end
+
+    #: () -> void
+    def update_pagination
+      @paginator.per_page = visible_item_count
+      @paginator.update_total_pages(@filtered_items.length)
+      @paginator.page = @offset / [visible_item_count, 1].max
+    end
+  end
+end