charming 0.1.2 → 0.1.3

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

@@ -1,119 +1,117 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class Form
-        # Field is the abstract base class for Form fields. Subclasses define `default_value`
-        # and `render_control` (or override `render`); the base class supplies validation,
-        # help-line rendering, error-line rendering, and value lookup against the form state.
-        class Field < Component
-          # The field's name symbol, human-readable label, optional help text, and bound state hash.
-          attr_reader :name, :label, :help, :state
-
-          # *name* is the value key (a Symbol). *label* defaults to a humanized version of *name*.
-          # *required* enables a "is required" validator. *validate* is an optional callable
-          # (returning nil/true → ok, false → "is invalid", Array → messages, anything else → stringified).
-          # *help* is an optional muted helper line rendered under the field.
-          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
+  module Components
+    class Form
+      # Field is the abstract base class for Form fields. Subclasses define `default_value`
+      # and `render_control` (or override `render`); the base class supplies validation,
+      # help-line rendering, error-line rendering, and value lookup against the form state.
+      class Field < Component
+        # The field's name symbol, human-readable label, optional help text, and bound state hash.
+        attr_reader :name, :label, :help, :state
+
+        # *name* is the value key (a Symbol). *label* defaults to a humanized version of *name*.
+        # *required* enables a "is required" validator. *validate* is an optional callable
+        # (returning nil/true → ok, false → "is invalid", Array → messages, anything else → stringified).
+        # *help* is an optional muted helper line rendered under the field.
+        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
 
-          # Binds the field to the form's *state* hash, ensuring the field's per-field state
-          # and a default value are present.
-          def bind(state)
-            @state = state
-            state[:fields][name] ||= {}
-            state[:values][name] = default_value unless state[:values].key?(name)
-          end
+        # Binds the field to the form's *state* hash, ensuring the field's per-field state
+        # and a default value are present.
+        def bind(state)
+          @state = state
+          state[:fields][name] ||= {}
+          state[:values][name] = default_value unless state[:values].key?(name)
+        end
 
-          # Subclasses that participate in Tab/Enter navigation return true. Default is true.
-          def focusable?
-            true
-          end
+        # Subclasses that participate in Tab/Enter navigation return true. Default is true.
+        def focusable?
+          true
+        end
 
-          # Default key handler returns nil (no key handling). Subclasses override.
-          def handle_key(_event)
-            nil
-          end
+        # Default key handler returns nil (no key handling). Subclasses override.
+        def handle_key(_event)
+          nil
+        end
 
-          # Renders the field as a control line prefixed with ">" (active) or " " (inactive),
-          # optionally followed by the help line and any error lines.
-          def render(active: false)
-            line = "#{active ? ">" : " "} #{render_control}"
-            line = theme.selected.render(line) if active
-            [line, help_line, *error_lines].compact.join("\n")
-          end
+        # Renders the field as a control line prefixed with ">" (active) or " " (inactive),
+        # optionally followed by the help line and any error lines.
+        def render(active: false)
+          line = "#{active ? ">" : " "} #{render_control}"
+          line = theme.selected.render(line) if active
+          [line, help_line, *error_lines].compact.join("\n")
+        end
 
-          # Returns an array of validation error messages. Includes "is required" when
-          # the field is required and blank, plus any messages produced by the user validator.
-          def validate
-            messages = []
-            messages << "is required" if required? && blank?(value)
-            messages.concat(validator_messages) if @validator
-            messages
-          end
+        # Returns an array of validation error messages. Includes "is required" when
+        # the field is required and blank, plus any messages produced by the user validator.
+        def validate
+          messages = []
+          messages << "is required" if required? && blank?(value)
+          messages.concat(validator_messages) if @validator
+          messages
+        end
 
-          # The current value of this field from the bound state.
-          def value
-            state[:values][name]
-          end
+        # The current value of this field from the bound state.
+        def value
+          state[:values][name]
+        end
 
-          private
+        private
 
-          # The default value assigned to a freshly-bound field. Subclasses override.
-          def default_value
-            nil
-          end
+        # The default value assigned to a freshly-bound field. Subclasses override.
+        def default_value
+          nil
+        end
 
-          # Renders the control portion (label + value). Default: "Label: <value>".
-          def render_control
-            "#{label}: #{value}"
-          end
+        # Renders the control portion (label + value). Default: "Label: <value>".
+        def render_control
+          "#{label}: #{value}"
+        end
 
-          # True when the field was declared with `required: true`.
-          def required?
-            @required
-          end
+        # True when the field was declared with `required: true`.
+        def required?
+          @required
+        end
 
-          # True when *value* is nil, an empty string, or responds to `empty?` with true.
-          def blank?(value)
-            return true if value.nil?
-            return value.strip.empty? if value.is_a?(String)
+        # True when *value* is nil, an empty string, or responds to `empty?` with true.
+        def blank?(value)
+          return true if value.nil?
+          return value.strip.empty? if value.is_a?(String)
 
-            value.respond_to?(:empty?) && value.empty?
-          end
+          value.respond_to?(:empty?) && value.empty?
+        end
 
-          # Normalizes the user validator's return value into an array of error message strings.
-          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
+        # Normalizes the user validator's return value into an array of error message strings.
+        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
 
-          # The muted help line (with two-space indent) when help text was given.
-          def help_line
-            "  #{theme.muted.render(help)}" if help
-          end
+        # The muted help line (with two-space indent) when help text was given.
+        def help_line
+          "  #{theme.muted.render(help)}" if help
+        end
 
-          # The list of error lines (with two-space indent) for any errors stored against this field.
-          def error_lines
-            Array(state[:errors][name]).map { |message| "  #{theme.warn.render(message)}" }
-          end
+        # The list of error lines (with two-space indent) for any errors stored against this field.
+        def error_lines
+          Array(state[:errors][name]).map { |message| "  #{theme.warn.render(message)}" }
+        end
 
-          # Converts a snake_case symbol/string to a humanized "Capitalized" string.
-          def humanize(value)
-            value.to_s.tr("_", " ").capitalize
-          end
+        # Converts a snake_case symbol/string to a humanized "Capitalized" string.
+        def humanize(value)
+          value.to_s.tr("_", " ").capitalize
         end
       end
     end

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

@@ -1,69 +1,67 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class Form
-        # Input is a single-line Form field backed by a TextInput widget. The cursor position
-        # is persisted in the form's per-field state so the field can be refocused mid-edit.
-        class Input < Field
-          # *value* is the initial text. *placeholder* is shown when the value is empty.
-          # *width* optionally constrains the rendered width. All other options are forwarded
-          # to Field (label, required, validate, help, theme).
-          def initialize(name, value: "", placeholder: "", width: nil, **options)
-            super(name, **options)
-            @initial_value = value
-            @placeholder = placeholder
-            @width = width
-          end
+  module Components
+    class Form
+      # Input is a single-line Form field backed by a TextInput widget. The cursor position
+      # is persisted in the form's per-field state so the field can be refocused mid-edit.
+      class Input < Field
+        # *value* is the initial text. *placeholder* is shown when the value is empty.
+        # *width* optionally constrains the rendered width. All other options are forwarded
+        # to Field (label, required, validate, help, theme).
+        def initialize(name, value: "", placeholder: "", width: nil, **options)
+          super(name, **options)
+          @initial_value = value
+          @placeholder = placeholder
+          @width = width
+        end
 
-          # Binds the field to the form state, sets the initial value if absent, and initializes
-          # the per-field cursor offset to the end of the value.
-          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
+        # Binds the field to the form state, sets the initial value if absent, and initializes
+        # the per-field cursor offset to the end of the value.
+        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
 
-          # Forwards key events to the underlying TextInput, syncing the value and cursor
-          # back into the form state. Returns :handled when the event was consumed.
-          def handle_key(event)
-            text_input = input
-            result = text_input.handle_key(event)
-            return nil unless result == :handled
+        # Forwards key events to the underlying TextInput, syncing the value and cursor
+        # back into the form state. Returns :handled when the event was consumed.
+        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
+          state[:values][name] = text_input.value
+          field_state[:cursor] = text_input.cursor
+          :handled
+        end
 
-          private
+        private
 
-          # The default value for a freshly-bound field is the *value* passed at construction.
-          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
 
-          # Renders the field as "Label: <text input>".
-          def render_control
-            "#{label}: #{input.render}"
-          end
+        # Renders the field as "Label: <text input>".
+        def render_control
+          "#{label}: #{input.render}"
+        end
 
-          # Builds a fresh TextInput each render, seeded from the current form-state value
-          # and the persisted cursor offset.
-          def input
-            TextInput.new(
-              value: value.to_s,
-              placeholder: @placeholder,
-              width: @width,
-              cursor: field_state[:cursor]
-            )
-          end
+        # Builds a fresh TextInput each render, seeded from the current form-state value
+        # and the persisted cursor offset.
+        def input
+          TextInput.new(
+            value: value.to_s,
+            placeholder: @placeholder,
+            width: @width,
+            cursor: field_state[:cursor]
+          )
+        end
 
-          # Returns the per-field state hash for this field.
-          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/note.rb

@@ -1,39 +1,37 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    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
+  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
 
-          # Binds the field to the form state but does not create any per-field storage.
-          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
 
-          # Notes are never focusable and therefore excluded from Tab/Enter traversal.
-          def focusable?
-            false
-          end
+        # Notes are never focusable and therefore excluded from Tab/Enter traversal.
+        def focusable?
+          false
+        end
 
-          # Notes never produce validation errors.
-          def validate
-            []
-          end
+        # Notes never produce validation errors.
+        def validate
+          []
+        end
 
-          # Returns the literal text, ignoring the *active:* flag (notes have no focus state).
-          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,110 +1,108 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    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
+  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
 
-          # Binds the field, then ensures the persisted selection (or initial/derived one) is applied.
-          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
 
-          # 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
+        # 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
 
-          # The options array (used as the source of truth for default value and clamp).
-          attr_reader :options
+        # The options array (used as the source of truth for default value and clamp).
+        attr_reader :options
 
-          # The default value is the option at the clamped initial selected index.
-          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
 
-          # Renders the field as "Label: <display value>".
-          def render_control
-            "#{label}: #{display_value}"
-          end
+        # Renders the field as "Label: <display value>".
+        def render_control
+          "#{label}: #{display_value}"
+        end
 
-          # Returns the stringified value via the configured option label callable.
-          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
 
-          # 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
+        # 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
 
-          # 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
+        # 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
 
-          # 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
+        # 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
 
-          # The currently persisted selected index (or the initial index when unset).
-          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
 
-          # Clamps the initial selected index to the valid range.
-          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
 
-          # Clamps *index* to the valid range. Returns 0 when there are no options.
-          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
 
-          # Returns the index of *option* in the options array, or nil when absent.
-          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
 
-          # Returns the per-field state hash for this field.
-          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