charming 0.1.0

data/lib/charming/components/activity_indicator.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # ActivityIndicator renders a color-gradient progress or loading indicator
+    # as styled text. It produces a fixed-width row of characters whose colors
+    # interpolate between two gradient endpoints (or cycle through a single
+    # color). A label can be appended after the bar and an ellipsis that cycles
+    # through frames, useful for "loading" state display. Call `tick` to advance
+    # the frame counter, and call `render` to produce the styled output string.
+    class ActivityIndicator < Component
+      # Default character pool used for generating each position's character via stable hashing.
+      DEFAULT_CHARS = "0123456789abcdefABCDEF~!@#$%^&*+=_".chars.freeze
+
+      # The default two-color gradient applied across the bar width (red to cyan).
+      # The cyan endpoint mirrors the Phosphor theme palette's "cyan" token so the bar
+      # remains legible on Phosphor's dark navy background; gradient: accepts raw hex,
+      # so callers using a different theme should pass their own endpoints.
+      DEFAULT_GRADIENT = ["#ff0000", "#6FD0E3"].freeze
+
+      # The default label color for ellipsis and text portions when no custom
+      # label_style is provided.
+      DEFAULT_LABEL_COLOR = "#cccccc"
+
+      # Ellipsis frame sequence: four states cycle through "., "..", "...", and "" (empty).
+      ELLIPSIS_FRAMES = [".", "..", "...", ""].freeze
+
+      # Number of frames in the animation cycle before the indicator pattern repeats.
+      FRAME_COUNT = 10
+
+      # FNV-1a variant constants used by stable_hash for reproducible character selection per position.
+      FNV_OFFSET = 2_166_136_261
+      FNV_PRIME = 16_777_619
+      FNV_MASK = 0xffffffff
+
+      attr_reader :width, :label, :index, :seed, :chars, :gradient, :label_style
+
+      # Initializes a new ActivityIndicator with configurable visual parameters.
+      # width       — Display width of the gradient bar in characters (minimum 1). Default: 10.
+      # label       — Optional text label shown adjacent to the indicator.
+      # index       — Initial frame index for the ellipsis/frame animations. Default: 0.
+      # seed        — Hash seed that determines which characters appear at each position.
+      # chars       — Character pool to draw from (default is DEFAULT_CHARS).
+      # gradient    — Two-element array of hex color strings ["#rrggbb", "#rrggbb"] for interpolation.
+      # label_style — A Style object to use for rendering the label text; falls back to a gray foreground.
+      def initialize(width: 10, label: nil, index: 0, seed: 0, chars: DEFAULT_CHARS,
+        gradient: DEFAULT_GRADIENT, label_style: nil)
+        super()
+        raise ArgumentError, "chars cannot be empty" if chars.empty?
+
+        @width = [width.to_i, 1].max
+        @label = label
+        @index = index.to_i
+        @seed = seed
+        @chars = chars.map(&:to_s)
+        @gradient = gradient
+        @label_style = label_style
+      end
+
+      # Advances the frame counter forward by +count+ steps, allowing the displayed pattern to change.
+      # Accepts an integer count (converted via +to_i+). Returns self for chaining.
+      def tick(count = 1)
+        @index += count.to_i
+        self
+      end
+
+      # Renders the activity indicator as a styled string. If a label was provided,
+      # produces "bar ellipsis" alongside it; otherwise produces only the gradient bar.
+      # Returns a formatted string suitable for terminal rendering.
+      def render
+        return indicator unless label
+
+        "#{indicator} #{styled_label}#{styled_ellipsis}"
+      end
+
+      private
+
+      # Renders the full gradient bar as an array of styled characters joined into a single string.
+      # Each character at +position+ is selected by hashing together seed, frame, and position —
+      # making the pattern stable across renders — then styled with the interpolated gradient color
+      # at that position.
+      def indicator
+        Array.new(width) { |position| styled_char(position) }.join
+      end
+
+      # Selects a character for the bar at the given +position+, styles it with the gradient color
+      # interpolated for that position, and returns the result as a formatted string via +render+.
+      def styled_char(position)
+        style.foreground(color_at(position)).render(char_at(position))
+      end
+
+      # Chooses a character from self.chars by hashing seed:frame:position together with a stable
+      # FNV-1a hash. The resulting index is modulated against the character pool length, ensuring
+      # reproducible output across renders.
+      def char_at(position)
+        chars.fetch(stable_hash("#{seed}:#{frame}:#{position}") % chars.length)
+      end
+
+      # Renders the label text in its own style (or fallback gray color) via a Style renderer call.
+      def styled_label
+        label_style_or_default.render(label.to_s)
+      end
+
+      # Renders an ellipsis frame (".", "..", "...", or empty) based on (index / 4) mod 4, styled with the label style.
+      def styled_ellipsis
+        label_style_or_default.render(ellipsis_frame)
+      end
+
+      # Returns the current ellipsis frame string: one of ".", "..", "...", "". Cycles through four frames per tick.
+      def ellipsis_frame
+        ELLIPSIS_FRAMES.fetch((index / 4) % ELLIPSIS_FRAMES.length)
+      end
+
+      # Returns the label style if set, otherwise produces a gray foreground style for fallback rendering.
+      def label_style_or_default
+        label_style || style.foreground(DEFAULT_LABEL_COLOR)
+      end
+
+      # Interpolates between gradient[0] and gradient[1] at the fractional +position+ (0.0 to 1.0).
+      # Returns the first gradient color if width is 1; otherwise returns a blended hex string based on position.
+      def color_at(position)
+        return gradient.first unless width > 1
+
+        blend(gradient.first, gradient.last, position / (width - 1).to_f)
+      end
+
+      # Blends two hex colors by interpolating their red/green/blue components at fractional +amount+.
+      # Accepts strings like "#ff0000" and produces a new "#rrggbb" string.
+      def blend(start_hex, end_hex, amount)
+        start_rgb = rgb(start_hex)
+        end_rgb = rgb(end_hex)
+        mixed = start_rgb.zip(end_rgb).map { |from, to| (from + ((to - from) * amount)).round }
+        "#%02x%02x%02x" % mixed
+      end
+
+      # Decomposes a hex color string ("#rrggbb") into an array of three integers [r, g, b].
+      def rgb(hex)
+        value = hex.to_s.delete_prefix("#")
+        raise ArgumentError, "gradient colors must be #rrggbb" unless value.match?(/\A[0-9a-fA-F]{6}\z/)
+
+        [value[0..1], value[2..3], value[4..5]].map { |part| part.to_i(16) }
+      end
+
+      # Advances the animation frame counter, wrapping around after +FRAME_COUNT+ (10) steps.
+      def frame
+        index % FRAME_COUNT
+      end
+
+      # Produces a deterministic integer hash from the input string using FNV-1a hashing, ensuring the same
+      # characters appear at the same positions across multiple renderings of this indicator.
+      def stable_hash(value)
+        value.bytes.reduce(FNV_OFFSET) do |hash, byte|
+          ((hash ^ byte) * FNV_PRIME) & FNV_MASK
+        end
+      end
+    end
+  end
+end

data/lib/charming/components/command_palette.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # CommandPalette renders a fuzzy-searchable command picker UI. It wraps a TextInput for search
+    # input and a List for result display, dispatching key events between them. Users type to filter
+    # the registered commands by label match, navigate with up/down/home/end keys (delegated to List),
+    # confirm a selection with Enter (returns [:selected, command]), or cancel with Escape (returns :cancelled).
+    # State is serializable as a hash of value/cursor/selected_index for session persistence.
+    class CommandPalette < Component
+      Command = Data.define(:label, :value)
+
+      # A single command palette entry: a human-readable +label+ and a callable or
+      # method symbol +value+ that gets executed when the user selects it.
+      attr_reader :commands, :input
+
+      # Initializes the dropdown widget with a list of Command entries and search
+      # parameters for building the underlying TextInput (placeholder text, cursor
+      # position, value) and List (display height, initial selection). Returns void;
+      # the state is later serializable via +state+ for session persistence.
+      def initialize(commands:, placeholder: "Search commands", height: nil, value: "", cursor: nil, selected_index: 0, theme: nil)
+        super(theme: theme)
+        @commands = commands
+        @height = height
+        @input = TextInput.new(value: value, placeholder: placeholder, cursor: cursor)
+        @list = build_list(selected_index: selected_index)
+      end
+
+      # Returns the currently displayed Command entry in the List at the time of calling.
+      # Returns nil if no entry is highlighted (i.e., user has opened the palette but not
+      # moved the selection). Useful for retrieving the result after key handling.
+      def selected_command
+        list.selected_item
+      end
+
+      # Collects the current state of the TextInput and List into a serializable hash
+      # suitable for round-trip storage in session. Returns {value:, cursor:, selected_index:}.
+      def state
+        {
+          value: input.value,
+          cursor: input.cursor,
+          selected_index: list.selected_index
+        }
+      end
+
+      # Handles key events by routing them to the appropriate sub-component: Escape kills the
+      # palette returning :cancelled; up/down/home/end keys go to the List selection handler
+      # via handle_list_key; all other keys (including typed characters) are passed to the TextInput
+      # which manages cursor position and input filtering. If a list key match fails, falls through
+      # to the TextInput handler. Returns nil/nil if no handler consumed the event, or :cancelled when
+      # Escape is pressed.
+      def handle_key(event)
+        key = Charming.key_of(event)
+        return :cancelled if key == :escape
+
+        return handle_list_key(event) if list_key?(key)
+
+        handle_input_key(event)
+      end
+
+      # Renders the command palette as a vertically-stacked text representation: the search TextInput
+      # row on line 1, and then the filtered List results (or "No commands found") on subsequent lines.
+      # Returns a multiline string suitable for terminal rendering.
+      def render
+        [input.render, render_results].join("\n")
+      end
+
+      private
+
+      attr_reader :height, :list
+
+      # Delegates key handling entirely to the internal List widget, which manages up/down/home/end selection.
+      # Returns whatever the List's handle_key returns (typically nil or the symbol from the subclass).
+      def handle_list_key(event)
+        list.handle_key(event)
+      end
+
+      # Passes the key event to the TextInput for cursor position and search text management.
+      # If the input returns :handled, rebuilds the List so that filtering is re-evaluated against
+      # the new input value. Returns nil/nil if no handler consumed the event.
+      def handle_input_key(event)
+        result = input.handle_key(event)
+        @list = build_list if result == :handled
+        result
+      end
+
+      # Checks whether the given key is a List-navigation key (up/down/home/end). Returns true for those keys
+      # so they can be dispatched via +handle_list_key+ rather than falling through to TextInput.
+      def list_key?(key)
+        %i[up down home end enter].include?(key)
+      end
+
+      # Renders the filtered results section below the search input. If no commands match the current filter text,
+      # returns "No commands found"; otherwise renders the List widget's styled display string. Returns a single-line string.
+      def render_results
+        return "No commands found" if filtered_commands.empty?
+
+        list.render
+      end
+
+      # Builds a new List from the currently filtered commands at the given selected_index height and label extractor.
+      # The +selected_index+ parameter defaults to the last known value in +list+ to preserve scroll position across rebuilds.
+      def build_list(selected_index: list&.selected_index || 0)
+        List.new(items: filtered_commands, selected_index: selected_index, height: height, label: :label.to_proc, theme: theme)
+      end
+
+      # Returns the full commands array when input value is empty; otherwise a subset whose labels match case-insensitively
+      # against the current TextInput value. Used to drive the fuzzy search behavior. Returns an Array of Command entries.
+      def filtered_commands
+        return commands if input.value.empty?
+
+        commands.select do |command|
+          command.label.downcase.include?(input.value.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/charming/components/keyboard_handler.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # KeyboardHandler is a mixin module that provides keyboard event dispatch by mapping symbolic key names
+    # to private method calls. Implementors must define a constant +KEY_ACTIONS+ as a hash where each key is
+    # a symbol (e.g., :up, :down, :enter) and each value is the target method name (e.g., :move_up). Call
+    # +handle_key(event)+ with any event object; it uses Charming.key_of to resolve the raw event to a symbol,
+    # looks up the corresponding action in KEY_ACTIONS, sends that method on self, and returns :handled if an
+    # action was found. Returns nil (via :handled being truthy or not) when no matching key exists.
+    module KeyboardHandler
+      def handle_key(event)
+        key = Charming.key_of(event)
+        action = self.class.const_get(:KEY_ACTIONS)[key]
+        return unless action
+
+        send(action)
+        :handled
+      end
+    end
+  end
+end

data/lib/charming/components/list.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    class List < Component
+      include KeyboardHandler
+
+      # Maps navigation key symbols to instance methods consumed by the KeyboardHandler
+      # mixin: :up moves selection up, :down moves down, :home jumps to first item,
+      # :end jumps to last. See Viewport#KEY_ACTIONS and Table#KEY_ACTIONS for identical pattern.
+      KEY_ACTIONS = {
+        up: :move_up,
+        down: :move_down,
+        home: :move_home,
+        end: :move_end
+      }.freeze
+
+      attr_reader :items, :selected_index
+
+      def initialize(items:, selected_index: 0, height: nil, label: nil, theme: nil)
+        super(theme: theme)
+        @items = items
+        @selected_index = selected_index
+        @height = height
+        @label = label || :to_s.to_proc
+        clamp_position
+      end
+
+      def handle_key(event)
+        return [:selected, selected_item] if Charming.key_of(event) == :enter && selected_item
+
+        super
+      end
+
+      def handle_mouse(event)
+        return nil unless @height
+        return nil unless event.respond_to?(:click?) && event.click?
+
+        clicked = event.y
+        return nil if clicked.negative? || clicked >= visible_items.length
+
+        @selected_index = viewport_start + clicked
+        clamp_position
+        :handled
+      end
+
+      def selected_item
+        items[selected_index]
+      end
+
+      def render
+        visible_items.each_with_index.map do |item, index|
+          render_item(item, viewport_start + index)
+        end.join("\n")
+      end
+
+      private
+
+      def move_up
+        @selected_index -= 1 if selected_index.positive?
+      end
+
+      def move_down
+        @selected_index += 1 if selected_index < items.length - 1
+      end
+
+      def move_home
+        @selected_index = 0
+      end
+
+      def move_end
+        @selected_index = items.length - 1 unless items.empty?
+      end
+
+      def visible_items
+        items[viewport_start, viewport_height] || []
+      end
+
+      def viewport_start
+        return 0 unless @height
+
+        (selected_index - @height + 1).clamp(0, max_viewport_start)
+      end
+
+      def viewport_height
+        @height || items.length
+      end
+
+      def max_viewport_start
+        [items.length - @height, 0].max
+      end
+
+      def render_item(item, index)
+        prefix = (index == selected_index) ? "> " : "  "
+        rendered = "#{prefix}#{@label.call(item)}"
+        (index == selected_index) ? theme.selected.render(rendered) : rendered
+      end
+
+      def clamp_position
+        @selected_index = 0 if items.empty?
+        @selected_index = selected_index.clamp(0, items.length - 1) unless items.empty?
+      end
+    end
+  end
+end

data/lib/charming/components/modal.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    class Modal < Component
+      def initialize(content:, title: nil, help: nil, width: 52, style: nil, theme: nil)
+        super(theme: theme)
+        @content = content
+        @title = title
+        @help = help
+        @width = width
+        @style = style
+      end
+
+      def render
+        box(column(*lines, gap: 1), style: modal_style)
+      end
+
+      private
+
+      attr_reader :content, :title, :help, :width
+
+      def lines
+        [title_line, help_line, render_content].compact
+      end
+
+      def title_line
+        text(title, style: theme.title.align(:center).width(title_width)) if title
+      end
+
+      def help_line
+        text(help, style: theme.muted) if help
+      end
+
+      def render_content
+        content.respond_to?(:render) ? render_component(content) : content.to_s
+      end
+
+      def modal_style
+        @style || theme.modal.width(width)
+      end
+
+      def title_width
+        [width - 8, 0].max
+      end
+    end
+  end
+end

data/lib/charming/components/progressbar.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    class Progressbar < Component
+      attr_accessor :total, :current, :label, :complete, :incomplete, :bar_format
+
+      def initialize(total:, complete: "=", incomplete: " ", bar_format: :classic, label: nil)
+        super()
+        @total = [total.to_i, 0].max
+        @complete = complete.to_s
+        @incomplete = incomplete.to_s
+        @bar_format = bar_format.to_sym
+        @label = label
+        @current = 0
+      end
+
+      def tick(count = 1)
+        update(@current + count)
+        self
+      end
+
+      def update(value)
+        @current = value.to_i.clamp(0, @total)
+        self
+      end
+
+      def complete!
+        @current = @total
+        self
+      end
+
+      def render
+        width = [@total, 1].max
+        completed = completed_width(width)
+        incomplete = width - completed
+        incomplete -= 1 if @current.zero?
+        bar = (@complete * completed) + (@incomplete * incomplete)
+        result = "[" + bar + "]"
+
+        return result unless @label
+
+        "#{result} #{@label}"
+      end
+
+      private
+
+      def completed_width(width)
+        return 0 unless @total.positive?
+
+        ((width * @current) / @total.to_f).round
+      end
+    end
+  end
+end

data/lib/charming/components/spinner.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Charming
+  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
+
+      def tick
+        @index = (index + 1) % frames.length
+        self
+      end
+
+      def render
+        return frame unless label
+
+        "#{frame} #{label}"
+      end
+
+      private
+
+      def frame
+        frames.fetch(index % frames.length)
+      end
+    end
+  end
+end

data/lib/charming/components/table.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "tty-table"
+
+module Charming
+  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)
+        super()
+        @header = Array(header).map(&:to_s)
+        @rows = Array(rows)
+        @selected_index = clamp_index(selected_index)
+      end
+
+      def handle_key(event)
+        return nil if rows.empty?
+
+        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
+
+        @selected_index = clicked
+        :handled
+      end
+
+      def selected_row
+        rows[selected_index]
+      end
+
+      def render
+        return "(empty table)" if header.empty? && rows.empty?
+
+        normalized = rows.map { |row| normalize_row(row) }
+        lines = TTY::Table.new(header: header, rows: normalized)
+          .render(:unicode)
+          .lines(chomp: true)
+
+        compact_layout(lines)
+      end
+
+      private
+
+      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
+
+        kept = cells.first(header.length - 1)
+        merged = cells[(header.length - 1)..].join(" ")
+        kept + [merged]
+      end
+
+      def compact_layout(lines)
+        return lines.join("\n") if lines.length < 4
+
+        top, header_line, _separator, *rest = lines
+        body = rest.first(rows.length)
+        bottom = rest[rows.length]
+
+        highlighted = body.each_with_index.map do |line, index|
+          (index == selected_index) ? "\e[7m#{line}\e[m" : line
+        end
+
+        [top, header_line, *highlighted, bottom].compact.join("\n")
+      end
+
+      def move_up
+        @selected_index -= 1 if selected_index.positive?
+      end
+
+      def move_down
+        @selected_index += 1 if selected_index < rows.length - 1
+      end
+
+      def move_home
+        @selected_index = 0
+      end
+
+      def move_end
+        @selected_index = rows.length - 1
+      end
+
+      def clamp_index(value)
+        return 0 if rows.empty?
+
+        value.to_i.clamp(0, rows.length - 1)
+      end
+    end
+  end
+end