charming 0.1.0 → 0.1.1

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      class Form
+        class Field < Component
+          attr_reader :name, :label, :help, :state
+
+          def initialize(name, label: nil, required: false, validate: nil, help: nil, theme: nil)
+            super(theme: theme)
+            @name = name.to_sym
+            @label = label || humanize(name)
+            @required = required
+            @validator = validate
+            @help = help
+          end
+
+          def bind(state)
+            @state = state
+            state[:fields][name] ||= {}
+            state[:values][name] = default_value unless state[:values].key?(name)
+          end
+
+          def focusable?
+            true
+          end
+
+          def handle_key(_event)
+            nil
+          end
+
+          def render(active: false)
+            line = "#{active ? ">" : " "} #{render_control}"
+            line = theme.selected.render(line) if active
+            [line, help_line, *error_lines].compact.join("\n")
+          end
+
+          def validate
+            messages = []
+            messages << "is required" if required? && blank?(value)
+            messages.concat(validator_messages) if @validator
+            messages
+          end
+
+          def value
+            state[:values][name]
+          end
+
+          private
+
+          def default_value
+            nil
+          end
+
+          def render_control
+            "#{label}: #{value}"
+          end
+
+          def required?
+            @required
+          end
+
+          def blank?(value)
+            return true if value.nil?
+            return value.strip.empty? if value.is_a?(String)
+
+            value.respond_to?(:empty?) && value.empty?
+          end
+
+          def validator_messages
+            result = @validator.call(value)
+            case result
+            when nil, true then []
+            when false then ["is invalid"]
+            when Array then result
+            else [result.to_s]
+            end
+          end
+
+          def help_line
+            "  #{theme.muted.render(help)}" if help
+          end
+
+          def error_lines
+            Array(state[:errors][name]).map { |message| "  #{theme.warn.render(message)}" }
+          end
+
+          def humanize(value)
+            value.to_s.tr("_", " ").capitalize
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      class Form
+        class Input < Field
+          def initialize(name, value: "", placeholder: "", width: nil, **options)
+            super(name, **options)
+            @initial_value = value
+            @placeholder = placeholder
+            @width = width
+          end
+
+          def bind(state)
+            super
+            state[:values][name] = @initial_value if state[:values][name].nil?
+            field_state[:cursor] = state[:values][name].to_s.length unless field_state.key?(:cursor)
+          end
+
+          def handle_key(event)
+            text_input = input
+            result = text_input.handle_key(event)
+            return nil unless result == :handled
+
+            state[:values][name] = text_input.value
+            field_state[:cursor] = text_input.cursor
+            :handled
+          end
+
+          private
+
+          def default_value
+            @initial_value
+          end
+
+          def render_control
+            "#{label}: #{input.render}"
+          end
+
+          def input
+            TextInput.new(
+              value: value.to_s,
+              placeholder: @placeholder,
+              width: @width,
+              cursor: field_state[:cursor]
+            )
+          end
+
+          def field_state
+            state[:fields][name]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      class Form
+        class Note < Field
+          def initialize(text, name: :note, theme: nil)
+            super(name, theme: theme)
+            @text = text
+          end
+
+          def bind(state)
+            @state = state
+          end
+
+          def focusable?
+            false
+          end
+
+          def validate
+            []
+          end
+
+          def render(active: false)
+            @text.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      class Form
+        class Select < Field
+          def initialize(name, options:, selected_index: 0, option_label: :to_s.to_proc, **field_options)
+            super(name, **field_options)
+            @options = options
+            @initial_selected_index = selected_index
+            @option_label = option_label
+          end
+
+          def bind(state)
+            super
+            ensure_selection
+          end
+
+          def handle_key(event)
+            selection = list
+            result = selection.handle_key(event)
+            return nil unless result == :handled
+
+            save_selection(selection.selected_index)
+            :handled
+          end
+
+          private
+
+          attr_reader :options
+
+          def default_value
+            options[clamped_initial_index]
+          end
+
+          def render_control
+            "#{label}: #{display_value}"
+          end
+
+          def display_value
+            value.nil? ? "" : @option_label.call(value)
+          end
+
+          def list
+            List.new(items: options, selected_index: selected_index, label: @option_label, theme: theme)
+          end
+
+          def ensure_selection
+            if field_state.key?(:selected_index)
+              save_selection(field_state[:selected_index])
+            elsif state[:values].key?(name)
+              save_selection(index_for(state[:values][name]) || clamped_initial_index)
+            else
+              save_selection(clamped_initial_index)
+            end
+          end
+
+          def save_selection(index)
+            field_state[:selected_index] = clamp_index(index)
+            state[:values][name] = options[field_state[:selected_index]]
+          end
+
+          def selected_index
+            field_state[:selected_index] || clamped_initial_index
+          end
+
+          def clamped_initial_index
+            clamp_index(@initial_selected_index)
+          end
+
+          def clamp_index(index)
+            return 0 if options.empty?
+
+            index.to_i.clamp(0, options.length - 1)
+          end
+
+          def index_for(option)
+            options.index(option)
+          end
+
+          def field_state
+            state[:fields][name]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      class Form
+        class Textarea < Field
+          def initialize(name, value: "", placeholder: "", width: nil, height: nil, **options)
+            super(name, **options)
+            @initial_value = value
+            @placeholder = placeholder
+            @width = width
+            @height = height
+          end
+
+          def bind(state)
+            super
+            state[:values][name] = @initial_value if state[:values][name].nil?
+            field_state[:cursor] = state[:values][name].to_s.length unless field_state.key?(:cursor)
+            field_state[:offset] ||= 0
+          end
+
+          def handle_key(event)
+            area = text_area
+            result = area.handle_key(event)
+            return nil unless result == :handled
+
+            state[:values][name] = area.value
+            field_state[:cursor] = area.cursor
+            field_state[:offset] = area.offset
+            field_state[:preferred_column] = area.preferred_column
+            :handled
+          end
+
+          def render(active: false)
+            label_line = "#{active ? ">" : " "} #{label}:"
+            label_line = theme.selected.render(label_line) if active
+            [label_line, *body_lines, help_line, *error_lines].compact.join("\n")
+          end
+
+          private
+
+          def default_value
+            @initial_value
+          end
+
+          def body_lines
+            text_area.render.lines(chomp: true).map { |line| "  #{line}" }
+          end
+
+          def text_area
+            TextArea.new(
+              value: value.to_s,
+              placeholder: @placeholder,
+              width: @width,
+              height: @height,
+              cursor: field_state[:cursor],
+              offset: field_state[:offset],
+              preferred_column: field_state[:preferred_column]
+            )
+          end
+
+          def field_state
+            state[:fields][name]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      class Form < Component
+        attr_reader :fields, :state
+
+        def initialize(fields:, state: nil, theme: nil)
+          super(theme: theme)
+          @fields = fields
+          @state = normalize_state(state || {})
+          bind_fields
+          clamp_focus
+        end
+
+        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
+
+        def values
+          state[:values]
+        end
+
+        def render
+          fields.each_with_index.map do |field, index|
+            field.render(active: index == state[:focus_index])
+          end.join("\n")
+        end
+
+        private
+
+        def normalize_state(value)
+          value[:values] ||= {}
+          value[:fields] ||= {}
+          value[:errors] ||= {}
+          value[:focus_index] ||= first_focusable_index || 0
+          value
+        end
+
+        def bind_fields
+          fields.each { |field| field.bind(state) }
+        end
+
+        def handle_current_field(event)
+          current_field&.handle_key(event)
+        end
+
+        def tab_direction(event)
+          return -1 if event.respond_to?(:shift) && event.shift
+
+          +1
+        end
+
+        def submit_shortcut?(event)
+          Charming.key_of(event) == :s && event.respond_to?(:ctrl) && event.ctrl
+        end
+
+        def advance_or_submit
+          return submit if last_focusable?
+
+          move_focus(+1)
+        end
+
+        def submit
+          state[:errors] = validation_errors
+          focus_first_error unless state[:errors].empty?
+          return :handled unless state[:errors].empty?
+
+          [:submitted, values.dup]
+        end
+
+        def validation_errors
+          fields.each_with_object({}) do |field, errors|
+            messages = field.validate
+            errors[field.name] = messages unless messages.empty?
+          end
+        end
+
+        def focus_first_error
+          invalid = fields.index { |field| field.focusable? && state[:errors].key?(field.name) }
+          state[:focus_index] = invalid if invalid
+        end
+
+        def current_field
+          fields[state[:focus_index]]
+        end
+
+        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
+
+        def last_focusable?
+          focusable_indices.last == state[:focus_index]
+        end
+
+        def focusable_indices
+          @focusable_indices ||= fields.each_index.select { |index| fields[index].focusable? }
+        end
+
+        def first_focusable_index
+          fields.each_index.find { |index| fields[index].focusable? }
+        end
+
+        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,104 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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, keymap: :vim)
+          super(theme: theme)
+          @items = items
+          @selected_index = selected_index
+          @height = height
+          @label = label || :to_s.to_proc
+          @keymap = keymap
+          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
+
+          Layout.selected_window_start(selected_index: selected_index, item_count: items.length, window_size: @height)
+        end
+
+        def viewport_height
+          @height || items.length
+        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
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Components
+      class Markdown < Component
+        def initialize(content:, width: nil, theme: nil, syntax_highlighting: true)
+          super(theme: theme)
+          @content = content
+          @width = width
+          @syntax_highlighting = syntax_highlighting
+        end
+
+        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,50 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+end