charming 0.1.1 → 0.1.3

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

@@ -1,30 +1,37 @@
 # 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
+  module Components
+    class Form
+      # Note is a non-interactive Form field that renders a static string of text. Notes
+      # never receive focus, never validate, and store no value — they are presentational
+      # only, useful for headings, dividers, or instructional text inside a form.
+      class Note < Field
+        # *text* is the literal string to render. *name* is unused (defaults to :note) and
+        # exists only because the Field base class requires a name.
+        def initialize(text, name: :note, theme: nil)
+          super(name, theme: theme)
+          @text = text
+        end
 
-          def bind(state)
-            @state = state
-          end
+        # Binds the field to the form state but does not create any per-field storage.
+        def bind(state)
+          @state = state
+        end
 
-          def focusable?
-            false
-          end
+        # Notes are never focusable and therefore excluded from Tab/Enter traversal.
+        def focusable?
+          false
+        end
 
-          def validate
-            []
-          end
+        # Notes never produce validation errors.
+        def validate
+          []
+        end
 
-          def render(active: false)
-            @text.to_s
-          end
+        # Returns the literal text, ignoring the *active:* flag (notes have no focus state).
+        def render(active: false)
+          @text.to_s
         end
       end
     end

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

@@ -1,87 +1,108 @@
 # 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
+  module Components
+    class Form
+      # Select is a single-choice Form field backed by a List widget. The selected option
+      # becomes the field's value; navigation keys (up/down/home/end) cycle through options
+      # and Enter has no effect (selection is applied immediately on key release).
+      class Select < Field
+        # *options* is the array of selectable values. *selected_index* defaults to 0.
+        # *option_label* is a callable used to extract the display string (default: `to_s`).
+        # All other options are forwarded to 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
+        # Binds the field, then ensures the persisted selection (or initial/derived one) is applied.
+        def bind(state)
+          super
+          ensure_selection
+        end
 
-          def handle_key(event)
-            selection = list
-            result = selection.handle_key(event)
-            return nil unless result == :handled
+        # Forwards key events to the underlying List, syncing the chosen option index back
+        # into the field state. Returns :handled when consumed.
+        def handle_key(event)
+          selection = list
+          result = selection.handle_key(event)
+          return nil unless result == :handled
 
-            save_selection(selection.selected_index)
-            :handled
-          end
+          save_selection(selection.selected_index)
+          :handled
+        end
 
-          private
+        private
 
-          attr_reader :options
+        # The options array (used as the source of truth for default value and clamp).
+        attr_reader :options
 
-          def default_value
-            options[clamped_initial_index]
-          end
+        # The default value is the option at the clamped initial selected index.
+        def default_value
+          options[clamped_initial_index]
+        end
 
-          def render_control
-            "#{label}: #{display_value}"
-          end
+        # Renders the field as "Label: <display value>".
+        def render_control
+          "#{label}: #{display_value}"
+        end
 
-          def display_value
-            value.nil? ? "" : @option_label.call(value)
-          end
+        # Returns the stringified value via the configured option label callable.
+        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
+        # Builds a fresh List each render with the current options, selected index, label
+        # callable, and theme.
+        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
+        # Ensures the persisted selection is set, falling back to the field's initial index
+        # or the current stored value.
+        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
+        # Persists the chosen *index* and the corresponding option as the field's value.
+        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
+        # The currently persisted selected index (or the initial index when unset).
+        def selected_index
+          field_state[:selected_index] || clamped_initial_index
+        end
 
-          def clamped_initial_index
-            clamp_index(@initial_selected_index)
-          end
+        # Clamps the initial selected index to the valid range.
+        def clamped_initial_index
+          clamp_index(@initial_selected_index)
+        end
 
-          def clamp_index(index)
-            return 0 if options.empty?
+        # Clamps *index* to the valid range. Returns 0 when there are no options.
+        def clamp_index(index)
+          return 0 if options.empty?
 
-            index.to_i.clamp(0, options.length - 1)
-          end
+          index.to_i.clamp(0, options.length - 1)
+        end
 
-          def index_for(option)
-            options.index(option)
-          end
+        # Returns the index of *option* in the options array, or nil when absent.
+        def index_for(option)
+          options.index(option)
+        end
 
-          def field_state
-            state[:fields][name]
-          end
+        # Returns the per-field state hash for this field.
+        def field_state
+          state[:fields][name]
         end
       end
     end

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

@@ -1,68 +1,82 @@
 # 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
+  module Components
+    class Form
+      # Textarea is a multi-line Form field backed by a TextArea widget. The cursor offset,
+      # top-visible row, and preferred vertical column are all persisted in the form's
+      # per-field state so the field behaves consistently when refocused mid-edit.
+      class Textarea < Field
+        # *value* is the initial text. *placeholder* is shown when the value is empty.
+        # *width* and *height* constrain the rendered area. All other options are forwarded
+        # to Field (label, required, validate, help, theme).
+        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
+        # Binds the field, seeds the initial value, and initializes the cursor/offset state.
+        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
+        # Forwards key events to the underlying TextArea, syncing the value, cursor, offset,
+        # and preferred column back into the form state. Returns :handled when consumed.
+        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
+          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
+        # Renders the field with its label on the first line, body lines indented, and
+        # optional help/error lines below.
+        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
+        private
 
-          def default_value
-            @initial_value
-          end
+        # The default value for a freshly-bound field is the *value* passed at construction.
+        def default_value
+          @initial_value
+        end
 
-          def body_lines
-            text_area.render.lines(chomp: true).map { |line| "  #{line}" }
-          end
+        # Renders the multi-line body, indenting each line by two spaces.
+        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
+        # Builds a fresh TextArea each render, seeded from the current form-state value and
+        # the persisted cursor/offset/preferred_column.
+        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
+        # Returns the per-field state hash for this field.
+        def field_state
+          state[:fields][name]
         end
       end
     end

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

@@ -1,126 +1,153 @@
 # 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
+  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
 
-        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
+      # 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
+        result = handle_current_field(event)
+        return result if result
 
-          advance_or_submit if key == :enter
-        end
+        advance_or_submit if key == :enter
+      end
 
-        def values
-          state[:values]
-        end
+      # Returns a hash of `{field_name => value}` for the current field values.
+      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
+      # 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
+      private
 
-        def normalize_state(value)
-          value[:values] ||= {}
-          value[:fields] ||= {}
-          value[:errors] ||= {}
-          value[:focus_index] ||= first_focusable_index || 0
-          value
-        end
+      # 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
 
-        def bind_fields
-          fields.each { |field| field.bind(state) }
-        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
 
-        def handle_current_field(event)
-          current_field&.handle_key(event)
-        end
+      # Forwards *event* to the currently focused field and returns its result.
+      def handle_current_field(event)
+        current_field&.handle_key(event)
+      end
 
-        def tab_direction(event)
-          return -1 if event.respond_to?(:shift) && event.shift
+      # 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
+        +1
+      end
 
-        def submit_shortcut?(event)
-          Charming.key_of(event) == :s && event.respond_to?(:ctrl) && event.ctrl
-        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
 
-        def advance_or_submit
-          return submit if last_focusable?
+      # 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
+        move_focus(+1)
+      end
 
-        def submit
-          state[:errors] = validation_errors
-          focus_first_error unless state[:errors].empty?
-          return :handled unless state[:errors].empty?
+      # 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
+        [: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
+      # 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
 
-        def focus_first_error
-          invalid = fields.index { |field| field.focusable? && state[:errors].key?(field.name) }
-          state[:focus_index] = invalid if invalid
-        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
 
-        def current_field
-          fields[state[:focus_index]]
-        end
+      # Returns the field at the current focus index, or nil when out of range.
+      def current_field
+        fields[state[:focus_index]]
+      end
 
-        def move_focus(direction)
-          indices = focusable_indices
-          return nil if indices.empty?
+      # 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
+        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
+      # True when the current focus index is the last focusable field.
+      def last_focusable?
+        focusable_indices.last == state[:focus_index]
+      end
 
-        def focusable_indices
-          @focusable_indices ||= fields.each_index.select { |index| fields[index].focusable? }
-        end
+      # Indices of focusable fields, memoized.
+      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
+      # 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
 
-        def clamp_focus
-          return if focusable_indices.empty?
-          return if focusable_indices.include?(state[:focus_index])
+      # 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
+        state[:focus_index] = focusable_indices.first
       end
     end
   end