bubbles 0.0.5 → 0.1.0

data/lib/bubbles/paginator.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Bubbles
+  # Paginator provides pagination logic and rendering.
+  #
+  # Example:
+  #   items = (1..100).to_a
+  #   paginator = Bubbles::Paginator.new(per_page: 10)
+  #   paginator.update_total_pages(items.length)
+  #
+  #   # Get current page items
+  #   start_index, end_index = paginator.slice_bounds(items.length)
+  #   current_items = items[start_index...end_index]
+  #
+  #   # Navigation
+  #   paginator.next_page
+  #   paginator.prev_page
+  #
+  #   # Render pagination indicator
+  #   puts paginator.view
+  #
+  class Paginator
+    ARABIC = :arabic #: Symbol
+    DOTS = :dots #: Symbol
+
+    attr_accessor :type #: Symbol
+    attr_accessor :page #: Integer
+    attr_accessor :per_page #: Integer
+    attr_accessor :total_pages #: Integer
+    attr_accessor :active_dot #: String
+    attr_accessor :inactive_dot #: String
+    attr_accessor :arabic_format #: String
+    attr_accessor :key_style #: Lipgloss::Style?
+    attr_accessor :active_dot_style #: Lipgloss::Style?
+    attr_accessor :inactive_dot_style #: Lipgloss::Style?
+
+    #: (?type: Symbol, ?per_page: Integer) -> void
+    def initialize(type: ARABIC, per_page: 10)
+      @type = type
+      @page = 0
+      @per_page = per_page
+      @total_pages = 1
+
+      @active_dot = "●"
+      @inactive_dot = "○"
+
+      @arabic_format = "%d/%d"
+
+      @key_style = nil
+      @active_dot_style = nil
+      @inactive_dot_style = nil
+    end
+
+    #: (Integer) -> void
+    def update_total_pages(total_items)
+      @total_pages = [(total_items.to_f / @per_page).ceil, 1].max
+      # Clamp current page
+      @page = @page.clamp(0, @total_pages - 1)
+    end
+
+    #: (Integer) -> Integer
+    def items_on_page(total_items)
+      return 0 if total_items <= 0
+
+      start_index = @page * @per_page
+      remaining = total_items - start_index
+
+      [remaining, @per_page].min
+    end
+
+    #: (Integer) -> [Integer, Integer]
+    def slice_bounds(total_items)
+      start_index = @page * @per_page
+      end_index = [start_index + @per_page, total_items].min
+      [start_index, end_index]
+    end
+
+    #: () -> bool
+    def prev_page?
+      @page.positive?
+    end
+
+    #: () -> bool
+    def next_page?
+      @page < @total_pages - 1
+    end
+
+    #: () -> bool
+    def prev_page # rubocop:disable Naming/PredicateMethod
+      return false unless prev_page?
+
+      @page -= 1
+
+      true
+    end
+
+    #: () -> bool
+    def next_page # rubocop:disable Naming/PredicateMethod
+      return false unless next_page?
+
+      @page += 1
+
+      true
+    end
+
+    #: (Integer) -> bool
+    def go_to_page(page) # rubocop:disable Naming/PredicateMethod
+      new_page = page.clamp(0, @total_pages - 1)
+      return false if new_page == @page
+
+      @page = new_page
+
+      true
+    end
+
+    #: () -> String
+    def view
+      case @type
+      when DOTS
+        dots_view
+      else
+        arabic_view
+      end
+    end
+
+    private
+
+    #: () -> String
+    def arabic_view
+      text = format(@arabic_format, @page + 1, @total_pages)
+      (key_style = @key_style) ? key_style.render(text) : text
+    end
+
+    #: () -> String
+    def dots_view
+      dots = (0...@total_pages).map do |i|
+        if i == @page
+          render_active_dot
+        else
+          render_inactive_dot
+        end
+      end
+
+      dots.join(" ")
+    end
+
+    #: () -> String
+    def render_active_dot
+      (style = @active_dot_style) ? style.render(@active_dot) : @active_dot
+    end
+
+    #: () -> String
+    def render_inactive_dot
+      (style = @inactive_dot_style) ? style.render(@inactive_dot) : @inactive_dot
+    end
+  end
+end

data/lib/bubbles/progress.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "harmonica"
+
+module Bubbles
+  # Progress renders an animated progress bar.
+  #
+  # Example:
+  #   progress = Bubbles::Progress.new
+  #   progress.width = 40
+  #
+  #   # Static rendering
+  #   puts progress.view_as(0.5)  # 50%
+  #
+  #   # Animated rendering (use in bubbletea)
+  #   command = progress.set_percent(0.75)
+  #   # Then in update: progress.update(message)
+  #   puts progress.view
+  #
+  class Progress
+    class FrameMessage < Bubbletea::Message
+      attr_reader :id #: Integer
+      attr_reader :tag #: Integer
+
+      #: (id: Integer, tag: Integer) -> void
+      def initialize(id:, tag:)
+        super()
+        @id = id
+        @tag = tag
+      end
+    end
+
+    FPS = 60 #: Integer
+    DEFAULT_WIDTH = 40 #: Integer
+    SPRING_FREQUENCY = 5.0 #: Float
+    SPRING_DAMPING = 1.0 #: Float
+
+    # rubocop:disable Style/ClassVars
+    @@last_id = 0 #: Integer
+    @@id_mutex = Mutex.new #: Mutex
+
+    #: () -> Integer
+    def self.next_id
+      @@id_mutex.synchronize do
+        @@last_id += 1
+      end
+    end
+    # rubocop:enable Style/ClassVars
+
+    attr_accessor :width #: Integer
+    attr_accessor :full #: String
+    attr_accessor :full_color #: String
+    attr_accessor :empty #: String
+    attr_accessor :empty_color #: String
+    attr_accessor :show_percentage #: bool
+    attr_accessor :percent_format #: String
+    attr_accessor :percent_style #: Lipgloss::Style?
+    attr_accessor :use_gradient #: bool
+    attr_accessor :gradient_a #: String?
+    attr_accessor :gradient_b #: String?
+    attr_accessor :scale_gradient #: bool
+
+    attr_reader :id #: Integer
+
+    #: (?width: Integer, ?gradient: Array[String]?, ?scaled_gradient: Array[String]?, ?solid_fill: String?) -> void
+    def initialize(width: DEFAULT_WIDTH, gradient: nil, scaled_gradient: nil, solid_fill: nil)
+      @id = self.class.next_id
+      @tag = 0
+
+      @width = width
+      @full = "█"
+      @full_color = "#7571F9"
+      @empty = "░"
+      @empty_color = "#606060"
+
+      @show_percentage = true
+      @percent_format = " %3.0f%%"
+      @percent_style = nil
+
+      @percent_shown = 0.0
+      @target_percent = 0.0
+      @velocity = 0.0
+
+      @spring = Harmonica::Spring.new(
+        delta_time: Harmonica.fps(FPS),
+        angular_frequency: SPRING_FREQUENCY,
+        damping_ratio: SPRING_DAMPING
+      )
+
+      @use_gradient = false
+      @gradient_a = nil
+      @gradient_b = nil
+      @scale_gradient = false
+
+      if gradient
+        gradient(gradient[0], gradient[1], scaled: false)
+      elsif scaled_gradient
+        gradient(scaled_gradient[0], scaled_gradient[1], scaled: true)
+      elsif solid_fill
+        @full_color = solid_fill
+        @use_gradient = false
+      end
+    end
+
+    #: () -> nil
+    def init
+      nil
+    end
+
+    #: (Bubbletea::Message) -> [Progress, Bubbletea::Command?]
+    def update(message)
+      command = nil
+
+      case message
+      when FrameMessage
+        if message.id == @id && message.tag == @tag && animating?
+          @percent_shown, @velocity = @spring.update(
+            @percent_shown,
+            @velocity,
+            @target_percent
+          )
+
+          if (@percent_shown - @target_percent).abs < 0.001 && @velocity.abs < 0.001
+            @percent_shown = @target_percent
+            @velocity = 0.0
+          else
+            command = next_frame
+          end
+        end
+      end
+
+      [self, command]
+    end
+
+    #: () -> String
+    def view
+      view_as(@percent_shown)
+    end
+
+    #: (Float) -> String
+    def view_as(percent)
+      percent = percent.clamp(0.0, 1.0)
+
+      percentage_view = render_percentage(percent)
+      bar = render_bar(percent, percentage_view.length)
+
+      "#{bar}#{percentage_view}"
+    end
+
+    #: () -> Float
+    def percent
+      @target_percent
+    end
+
+    #: (Float) -> Bubbletea::Command
+    def set_percent(percent) # rubocop:disable Naming/AccessorMethodName
+      @target_percent = percent.clamp(0.0, 1.0)
+      @tag += 1
+
+      next_frame
+    end
+
+    #: (?Float) -> Bubbletea::Command
+    def increment_percent(amount = 1.0)
+      set_percent(percent + amount)
+    end
+
+    #: (?Float) -> Bubbletea::Command
+    def decrement_percent(amount = 1.0)
+      set_percent(percent - amount)
+    end
+
+    #: () -> bool
+    def animating?
+      (@percent_shown - @target_percent).abs >= 0.001
+    end
+
+    #: (String, String, ?scaled: bool) -> void
+    def gradient(color_a, color_b, scaled: false)
+      @use_gradient = true
+      @gradient_a = color_a
+      @gradient_b = color_b
+      @scale_gradient = scaled
+    end
+
+    private
+
+    #: () -> Bubbletea::Command
+    def next_frame
+      id = @id
+      tag = @tag
+      interval = 1.0 / FPS
+
+      Bubbletea.tick(interval) do
+        FrameMessage.new(id: id, tag: tag)
+      end
+    end
+
+    #: (Float, Integer) -> String
+    def render_bar(percent, text_width)
+      total_width = [@width - text_width, 0].max
+      filled_width = (total_width * percent).round
+      filled_width = filled_width.clamp(0, total_width)
+      empty_width = [total_width - filled_width, 0].max
+
+      filled = if @use_gradient && @gradient_a && @gradient_b
+                 render_gradient_fill(filled_width, total_width)
+               else
+                 render_solid_fill(filled_width)
+               end
+
+      empty = render_empty_fill(empty_width)
+
+      "#{filled}#{empty}"
+    end
+
+    #: (Integer) -> String
+    def render_solid_fill(width)
+      return "" if width <= 0
+
+      char = @full * width
+      colorize(char, @full_color)
+    end
+
+    #: (Integer) -> String
+    def render_empty_fill(width)
+      return "" if width <= 0
+
+      char = @empty * width
+      colorize(char, @empty_color)
+    end
+
+    #: (Integer, Integer) -> String
+    def render_gradient_fill(filled_width, total_width)
+      return "" if filled_width <= 0
+
+      result = ""
+
+      filled_width.times do |i|
+        p = if filled_width == 1
+              0.5
+            elsif @scale_gradient
+              i.to_f / (filled_width - 1)
+            else
+              i.to_f / [total_width - 1, 1].max
+            end
+
+        color = blend_colors(@gradient_a, @gradient_b, p)
+        result += colorize(@full, color)
+      end
+
+      result
+    end
+
+    #: (Float) -> String
+    def render_percentage(percent)
+      return "" unless @show_percentage
+
+      text = format(@percent_format, percent * 100)
+      (style = @percent_style) ? style.render(text) : text
+    end
+
+    #: (String, String) -> String
+    def colorize(text, color)
+      Lipgloss::Style.new.foreground(color).render(text)
+    end
+
+    #: (String?, String?, Float) -> String
+    def blend_colors(color_a, color_b, ratio)
+      a = color_a || @full_color
+      b = color_b || @full_color
+      Lipgloss::ColorBlend.blend(a, b, ratio)
+    end
+  end
+end

data/lib/bubbles/spinner/spinners.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Bubbles
+  module Spinners
+    LINE = {
+      frames: ["|", "/", "-", "\\"],
+      fps: 0.1,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    DOT = {
+      frames: ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"],
+      fps: 0.1,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    MINI_DOT = {
+      frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+      fps: 0.083,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    JUMP = {
+      frames: ["⢄", "⢂", "⢁", "⡁", "⡈", "⡐", "⡠"],
+      fps: 0.1,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    PULSE = {
+      frames: ["█", "▓", "▒", "░"],
+      fps: 0.125,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    POINTS = {
+      frames: ["∙∙∙", "●∙∙", "∙●∙", "∙∙●"],
+      fps: 0.143,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    GLOBE = {
+      frames: ["🌍", "🌎", "🌏"],
+      fps: 0.25,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    MOON = {
+      frames: ["🌑", "🌒", "🌓", "🌔", "🌕", "🌖", "🌗", "🌘"],
+      fps: 0.125,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    MONKEY = {
+      frames: ["🙈", "🙉", "🙊"],
+      fps: 0.333,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    METER = {
+      frames: [
+        "▱▱▱",
+        "▰▱▱",
+        "▰▰▱",
+        "▰▰▰",
+        "▰▰▱",
+        "▰▱▱",
+        "▱▱▱",
+      ],
+      fps: 0.143,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    HAMBURGER = {
+      frames: ["☱", "☲", "☴", "☲"],
+      fps: 0.333,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    ELLIPSIS = {
+      frames: ["", ".", "..", "..."],
+      fps: 0.333,
+    }.freeze #: Hash[Symbol, Array[String] | Float]
+
+    # @rbs DEFAULT:
+    DEFAULT = LINE #: Hash[Symbol, Array[String] | Float]
+  end
+end

data/lib/bubbles/spinner.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "spinner/spinners"
+
+module Bubbles
+  # Spinner is an animated activity indicator component.
+  #
+  # Example:
+  #   spinner = Bubbles::Spinner.new(spinner: Bubbles::Spinners::DOT)
+  #   spinner.style = Lipgloss::Style.new.foreground("205")
+  #
+  #   # In your model's init:
+  #   def init
+  #     [self, @spinner.tick]
+  #   end
+  #
+  #   # In your model's update:
+  #   def update(message)
+  #     case message
+  #     when Bubbles::Spinner::TickMessage
+  #       @spinner, command = @spinner.update(message)
+  #       [self, command]
+  #     end
+  #   end
+  #
+  #   # In your model's view:
+  #   def view
+  #     "#{@spinner.view} Loading..."
+  #   end
+  #
+  class Spinner
+    class TickMessage < Bubbletea::Message
+      attr_reader :id #: Integer
+      attr_reader :tag #: Integer
+
+      #: (id: Integer, tag: Integer) -> void
+      def initialize(id:, tag:)
+        super()
+
+        @id = id
+        @tag = tag
+      end
+    end
+
+    # @rbs self.@next_id: Integer
+    # @rbs self.@id_mutex: Mutex
+    @next_id = 0
+    @id_mutex = Mutex.new
+
+    class << self
+      #: () -> Integer
+      def next_id
+        @id_mutex.synchronize do
+          @next_id += 1
+        end
+      end
+    end
+
+    attr_reader :id #: Integer
+    attr_accessor :spinner #: Hash[Symbol, untyped]
+    attr_accessor :style #: Lipgloss::Style?
+
+    #: (?spinner: Hash[Symbol, untyped], ?style: Lipgloss::Style?) -> void
+    def initialize(spinner: Spinners::DEFAULT, style: nil)
+      @spinner = spinner
+      @style = style
+      @frame = 0
+      @id = self.class.next_id
+      @tag = 0
+    end
+
+    #: () -> [Spinner, Bubbletea::Command]
+    def init
+      [self, tick]
+    end
+
+    #: (Bubbletea::Message) -> [Spinner, Bubbletea::Command?]
+    def update(message)
+      case message
+      when TickMessage
+        return [self, nil] if message.id.positive? && message.id != @id
+        return [self, nil] if message.tag.positive? && message.tag != @tag
+
+        @frame = (@frame + 1) % frames.length
+        @tag += 1
+
+        [self, tick]
+      else
+        [self, nil]
+      end
+    end
+
+    #: () -> String
+    def view
+      return "(error)" if @frame >= frames.length
+
+      frame_str = frames[@frame]
+      (style = @style) ? style.render(frame_str) : frame_str
+    end
+
+    #: () -> Bubbletea::Command
+    def tick
+      current_id = @id
+      current_tag = @tag
+
+      Bubbletea.tick(fps) { TickMessage.new(id: current_id, tag: current_tag) }
+    end
+
+    private
+
+    #: () -> Array[String]
+    def frames
+      @spinner[:frames] || Spinners::DEFAULT[:frames]
+    end
+
+    #: () -> Float
+    def fps
+      @spinner[:fps] || Spinners::DEFAULT[:fps]
+    end
+  end
+end