charming 0.1.0 → 0.1.2

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      # Form is a multi-field form component with built-in focus traversal, validation, and
+      # submit/cancel handling. Fields are produced by `Form::Builder` (see `controller.form`)
+      # and bound to a per-form mutable state hash. Tab/Shift+Tab cycles focus through
+      # focusable fields, Enter advances to the next field (or submits on the last), Escape
+      # cancels, and Ctrl+S submits from any field.
+      class Form < Component
+        # The list of field objects and the mutable state hash the form is bound to.
+        attr_reader :fields, :state
+
+        # *fields* is the array of form field objects. *state* is a hash for storing field
+        # values/errors and the current focus index; usually `session[:forms][form_name]`.
+        def initialize(fields:, state: nil, theme: nil)
+          super(theme: theme)
+          @fields = fields
+          @state = normalize_state(state || {})
+          bind_fields
+          clamp_focus
+        end
+
+        # Handles key events: Escape cancels, Ctrl+S submits, Tab cycles focus, Enter advances
+        # or submits, and unhandled keys are passed to the focused field.
+        def handle_key(event)
+          key = Charming.key_of(event)
+          return :cancelled if key == :escape
+          return submit if submit_shortcut?(event)
+          return move_focus(tab_direction(event)) if key == :tab
+
+          result = handle_current_field(event)
+          return result if result
+
+          advance_or_submit if key == :enter
+        end
+
+        # Returns a hash of `{field_name => value}` for the current field values.
+        def values
+          state[:values]
+        end
+
+        # Renders each field on its own line, marking the active field with `active: true`.
+        def render
+          fields.each_with_index.map do |field, index|
+            field.render(active: index == state[:focus_index])
+          end.join("\n")
+        end
+
+        private
+
+        # Ensures the state hash has all the required sub-keys: :values, :fields, :errors, and
+        # a sensible :focus_index default.
+        def normalize_state(value)
+          value[:values] ||= {}
+          value[:fields] ||= {}
+          value[:errors] ||= {}
+          value[:focus_index] ||= first_focusable_index || 0
+          value
+        end
+
+        # Binds each field to the state hash so field updates write back into `state[:values]`.
+        def bind_fields
+          fields.each { |field| field.bind(state) }
+        end
+
+        # Forwards *event* to the currently focused field and returns its result.
+        def handle_current_field(event)
+          current_field&.handle_key(event)
+        end
+
+        # Returns -1 for Shift+Tab (backward), +1 for plain Tab (forward).
+        def tab_direction(event)
+          return -1 if event.respond_to?(:shift) && event.shift
+
+          +1
+        end
+
+        # True when the event is the submit shortcut (Ctrl+S).
+        def submit_shortcut?(event)
+          Charming.key_of(event) == :s && event.respond_to?(:ctrl) && event.ctrl
+        end
+
+        # On Enter: submit when the last focusable field is active, otherwise advance focus.
+        def advance_or_submit
+          return submit if last_focusable?
+
+          move_focus(+1)
+        end
+
+        # Validates all fields, focuses the first invalid one, and returns [:submitted, values]
+        # when there are no errors.
+        def submit
+          state[:errors] = validation_errors
+          focus_first_error unless state[:errors].empty?
+          return :handled unless state[:errors].empty?
+
+          [:submitted, values.dup]
+        end
+
+        # Runs each field's validator and collects per-field error messages.
+        def validation_errors
+          fields.each_with_object({}) do |field, errors|
+            messages = field.validate
+            errors[field.name] = messages unless messages.empty?
+          end
+        end
+
+        # Moves focus to the first focusable field with errors, when any.
+        def focus_first_error
+          invalid = fields.index { |field| field.focusable? && state[:errors].key?(field.name) }
+          state[:focus_index] = invalid if invalid
+        end
+
+        # Returns the field at the current focus index, or nil when out of range.
+        def current_field
+          fields[state[:focus_index]]
+        end
+
+        # Moves focus by *direction* (forward or backward) through the focusable fields.
+        def move_focus(direction)
+          indices = focusable_indices
+          return nil if indices.empty?
+
+          current = indices.index(state[:focus_index]) || 0
+          state[:focus_index] = indices[(current + direction) % indices.length]
+          :handled
+        end
+
+        # True when the current focus index is the last focusable field.
+        def last_focusable?
+          focusable_indices.last == state[:focus_index]
+        end
+
+        # Indices of focusable fields, memoized.
+        def focusable_indices
+          @focusable_indices ||= fields.each_index.select { |index| fields[index].focusable? }
+        end
+
+        # The first index of a focusable field, or nil when no fields are focusable.
+        def first_focusable_index
+          fields.each_index.find { |index| fields[index].focusable? }
+        end
+
+        # On initialization, ensures :focus_index points at a focusable field.
+        def clamp_focus
+          return if focusable_indices.empty?
+          return if focusable_indices.include?(state[:focus_index])
+
+          state[:focus_index] = focusable_indices.first
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+        VIM_KEYMAP = {
+          up: :k,
+          down: :j,
+          left: :h,
+          right: :l
+        }.freeze
+
+        def handle_key(event)
+          key = Charming.key_of(event)
+          action = key_actions[key]
+          return unless action
+
+          send(action)
+          :handled
+        end
+
+        private
+
+        def key_actions
+          base_key_actions.merge(normalized_keymap)
+        end
+
+        def base_key_actions
+          self.class.const_get(:KEY_ACTIONS)
+        end
+
+        def normalized_keymap
+          resolved_keymap.each_with_object({}) do |(action_key, keys), actions|
+            action = base_key_actions[action_key.to_sym]
+            next unless action
+
+            Array(keys).each { |key| actions[key.to_sym] = action }
+          end
+        end
+
+        def resolved_keymap
+          case @keymap
+          when :vim then VIM_KEYMAP
+          when nil then {}
+          else @keymap
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      # List is a vertically-scrollable selectable list. Supports keyboard navigation
+      # (up/down/home/end, Enter to activate) and mouse click selection. When a *height* is
+      # given, the list renders a fixed-height window over its items with auto-scroll
+      # keeping the selected item in view.
+      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
+
+        # The item array and the currently selected index within it.
+        attr_reader :items, :selected_index
+
+        # *items* is the array of selectable objects. *selected_index* defaults to 0.
+        # *height* optionally constrains the visible window; *label* is a callable that
+        # extracts the display string from an item (defaults to `to_s`).
+        # *keymap* selects the keybinding style (`:vim` enables h/j/k/l → left/down/up/right).
+        def initialize(items:, selected_index: 0, height: nil, label: nil, theme: nil, keymap: :vim)
+          super(theme: theme)
+          @items = items
+          @selected_index = selected_index
+          @height = height
+          @label = label || :to_s.to_proc
+          @keymap = keymap
+          clamp_position
+        end
+
+        # Handles key events. Returns `[:selected, item]` on Enter when an item is selected;
+        # otherwise delegates to the KeyboardHandler for navigation keys.
+        def handle_key(event)
+          return [:selected, selected_item] if Charming.key_of(event) == :enter && selected_item
+
+          super
+        end
+
+        # Handles mouse events: a click within the visible window selects the clicked row.
+        # Returns :handled on a successful click, nil otherwise.
+        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
+
+        # Returns the currently selected item, or nil when the list is empty.
+        def selected_item
+          items[selected_index]
+        end
+
+        # Renders the visible window of items, prefixing each with "> " (and applying the
+        # selected style) or "  ".
+        def render
+          visible_items.each_with_index.map do |item, index|
+            render_item(item, viewport_start + index)
+          end.join("\n")
+        end
+
+        private
+
+        # Moves the selection up one position.
+        def move_up
+          @selected_index -= 1 if selected_index.positive?
+        end
+
+        # Moves the selection down one position.
+        def move_down
+          @selected_index += 1 if selected_index < items.length - 1
+        end
+
+        # Moves the selection to the first item.
+        def move_home
+          @selected_index = 0
+        end
+
+        # Moves the selection to the last item (no-op when the list is empty).
+        def move_end
+          @selected_index = items.length - 1 unless items.empty?
+        end
+
+        # Returns the slice of items currently in the visible window.
+        def visible_items
+          items[viewport_start, viewport_height] || []
+        end
+
+        # Returns the index of the topmost visible item, computed so the selected item stays
+        # in view when the list is taller than the visible window.
+        def viewport_start
+          return 0 unless @height
+
+          Layout.selected_window_start(selected_index: selected_index, item_count: items.length, window_size: @height)
+        end
+
+        # Returns the number of items visible in the window (the configured *height* or the
+        # total item count when no height was set).
+        def viewport_height
+          @height || items.length
+        end
+
+        # Renders a single item: prefix with "> " (selected) or "  " (unselected), then apply
+        # the theme's selected style to the selected item's row.
+        def render_item(item, index)
+          prefix = (index == selected_index) ? "> " : "  "
+          rendered = "#{prefix}#{@label.call(item)}"
+          (index == selected_index) ? theme.selected.render(rendered) : rendered
+        end
+
+        # Resets the selection when the list is empty, otherwise clamps it to the valid range.
+        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
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      # Markdown renders Markdown source as ANSI-styled terminal text. Parsing is delegated to
+      # `Presentation::Markdown::Renderer`; set *syntax_highlighting* to false to disable
+      # Rouge-backed code block highlighting.
+      class Markdown < Component
+        # *content* is the Markdown source string. *width* optionally sets the wrap width.
+        # *syntax_highlighting* enables Rouge for code blocks (defaults to true).
+        def initialize(content:, width: nil, theme: nil, syntax_highlighting: true)
+          super(theme: theme)
+          @content = content
+          @width = width
+          @syntax_highlighting = syntax_highlighting
+        end
+
+        # Renders the Markdown body to a styled, terminal-safe string.
+        def render
+          Charming::Presentation::Markdown::Renderer.new(
+            content: @content,
+            width: @width,
+            theme: theme,
+            syntax_highlighting: @syntax_highlighting
+          ).render
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      # Modal is a centered, boxed overlay with an optional title, help line, and body content.
+      # The body may be a string, View, or Component; when it responds to `render`, its output
+      # is used. The result is wrapped in a UI::Style border with padding.
+      class Modal < Component
+        # *content* is the modal body. *title* (optional) is rendered centered at the top.
+        # *help* (optional) is rendered as a muted footer line. *width* is the modal's total width.
+        # *style* overrides the default `theme.modal` style.
+        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
+
+        # Renders the modal as a bordered, padded string with the title and help lines stacked
+        # above the content.
+        def render
+          box(column(*lines, gap: 1), style: modal_style)
+        end
+
+        private
+
+        attr_reader :content, :title, :help, :width
+
+        # Returns the array of non-nil lines: title, help, content.
+        def lines
+          [title_line, help_line, render_content].compact
+        end
+
+        # Returns the centered title line styled with the theme's title style, when a title was given.
+        def title_line
+          text(title, style: theme.title.align(:center).width(title_width)) if title
+        end
+
+        # Returns the help line styled with the theme's muted style, when help was given.
+        def help_line
+          text(help, style: theme.muted) if help
+        end
+
+        # Returns the rendered content string, calling `render` on the body when applicable.
+        def render_content
+          content.respond_to?(:render) ? render_component(content) : content.to_s
+        end
+
+        # Returns the modal's outer style: the user-provided style or `theme.modal` at the given width.
+        def modal_style
+          @style || theme.modal.width(width)
+        end
+
+        # Returns the title's display width, accounting for the modal's horizontal padding/border.
+        def title_width
+          [width - 8, 0].max
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      # Progressbar renders a fixed-width ASCII progress bar. The bar is sized to the configured
+      # *total* (in arbitrary units) and fills proportionally to the current value. Optionally
+      # appends a label after the bar.
+      class Progressbar < Component
+        # Public accessors: total units, current value, label text, completed and remaining
+        # characters, and the bar format symbol.
+        attr_accessor :total, :current, :label, :complete, :incomplete, :bar_format
+
+        # *total* is the maximum unit count. *complete* and *incomplete* are the characters used
+        # for filled and unfilled positions (default "=" and " "). *bar_format* is reserved for
+        # future format variants. *label* is an optional suffix shown after the bar.
+        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
+
+        # Advances the current value by *count* (default 1), clamping to `[0, total]`. Returns self.
+        def tick(count = 1)
+          update(@current + count)
+          self
+        end
+
+        # Sets the current value, clamping to `[0, total]`. Returns self.
+        def update(value)
+          @current = value.to_i.clamp(0, @total)
+          self
+        end
+
+        # Jumps the bar directly to 100% completion. Returns self.
+        def complete!
+          @current = @total
+          self
+        end
+
+        # Renders the bar as `[====  ]` (with the *label* appended when present).
+        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
+
+        # Returns the number of `complete` characters to draw, rounded to the nearest integer.
+        def completed_width(width)
+          return 0 unless @total.positive?
+
+          ((width * @current) / @total.to_f).round
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+
+        # Advances the frame index by one position, wrapping around. Returns self for chaining.
+        def tick
+          @index = (index + 1) % frames.length
+          self
+        end
+
+        # Renders the current frame, optionally followed by the label and a space.
+        def render
+          return frame unless label
+
+          "#{frame} #{label}"
+        end
+
+        private
+
+        # Returns the current frame string (with index modulo frame count to be safe).
+        def frame
+          frames.fetch(index % frames.length)
+        end
+      end
+    end
+  end
+end