charming 0.1.1 → 0.1.3

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

@@ -1,42 +1,53 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class EmptyState < Component
-        def initialize(message: "Nothing to show.", loading: false, loading_message: "Loading...", error: nil, error_message: nil, help: nil, theme: nil)
-          super(theme: theme)
-          @message = message
-          @loading = loading
-          @loading_message = loading_message
-          @error = error
-          @error_message = error_message
-          @help = help
-        end
-
-        def render
-          return loading_state if @loading
-          return error_state if error?
-
-          text @message, style: theme.muted
-        end
-
-        private
-
-        def loading_state
-          text @loading_message, style: theme.muted
-        end
-
-        def error_state
-          lines = [text(@error_message || @error.to_s, style: theme.warn)]
-          lines << text(@help, style: theme.muted) if @help.to_s.strip != ""
-
-          column(*lines)
-        end
-
-        def error?
-          @error.to_s.strip != "" || @error_message.to_s.strip != ""
-        end
+  module Components
+    # EmptyState is a placeholder component for screens with no content. Renders one of three
+    # states: a default "nothing to show" message, a "loading…" message, or an error message
+    # with optional help text.
+    class EmptyState < Component
+      # *message* is shown in the default state. *loading* switches to the loading message
+      # (overrides *message*). *loading_message* is the string rendered in the loading state.
+      # *error* and *error_message* switch to the error state (the string form takes precedence).
+      # *help* is an optional muted line shown below the error message.
+      def initialize(message: "Nothing to show.", loading: false, loading_message: "Loading...", error: nil, error_message: nil, help: nil, theme: nil)
+        super(theme: theme)
+        @message = message
+        @loading = loading
+        @loading_message = loading_message
+        @error = error
+        @error_message = error_message
+        @help = help
+      end
+
+      # Renders the appropriate state as styled text: loading → loading message, error →
+      # error message + help, otherwise the default message.
+      def render
+        return loading_state if @loading
+        return error_state if error?
+
+        text @message, style: theme.muted
+      end
+
+      private
+
+      # Renders the loading state as a muted line.
+      def loading_state
+        text @loading_message, style: theme.muted
+      end
+
+      # Renders the error state: the error message styled with the theme's warn style,
+      # optionally followed by a muted help line.
+      def error_state
+        lines = [text(@error_message || @error.to_s, style: theme.warn)]
+        lines << text(@help, style: theme.muted) if @help.to_s.strip != ""
+
+        column(*lines)
+      end
+
+      # True when either the *error* or *error_message* string is non-blank.
+      def error?
+        @error.to_s.strip != "" || @error_message.to_s.strip != ""
       end
     end
   end

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

@@ -1,46 +1,58 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class Form
-        class Builder
-          attr_reader :fields, :theme
-
-          def initialize(theme: nil)
-            @theme = theme
-            @fields = []
-          end
-
-          def input(name, **options)
-            fields << Input.new(name, **field_options(options))
-          end
-
-          def textarea(name, **options)
-            fields << Textarea.new(name, **field_options(options))
-          end
-
-          def select(name, **options)
-            fields << Select.new(name, **field_options(options))
-          end
-
-          def confirm(name, **options)
-            fields << Confirm.new(name, **field_options(options))
-          end
-
-          def note(text, **options)
-            fields << Note.new(text, **field_options(options))
-          end
-
-          def build(state:, theme: nil)
-            Components::Form.new(fields: fields, state: state, theme: theme || self.theme)
-          end
-
-          private
-
-          def field_options(options)
-            {theme: theme}.merge(options)
-          end
+  module Components
+    class Form
+      # Builder collects form field declarations inside a `form(:name) { ... }` block and
+      # assembles them into a Form component when `build` is called. Each declaration method
+      # appends a Field subclass instance to the builder's *fields* list.
+      class Builder
+        # The accumulated field list and the theme applied to each declared field.
+        attr_reader :fields, :theme
+
+        # Initializes an empty builder. *theme* is forwarded to every declared field unless
+        # the field declaration explicitly overrides it.
+        def initialize(theme: nil)
+          @theme = theme
+          @fields = []
+        end
+
+        # Appends a single-line Input field. *options* are passed through to Input.
+        def input(name, **options)
+          fields << Input.new(name, **field_options(options))
+        end
+
+        # Appends a multi-line Textarea field.
+        def textarea(name, **options)
+          fields << Textarea.new(name, **field_options(options))
+        end
+
+        # Appends a Select field with the given *options* array.
+        def select(name, **options)
+          fields << Select.new(name, **field_options(options))
+        end
+
+        # Appends a Confirm (boolean) field.
+        def confirm(name, **options)
+          fields << Confirm.new(name, **field_options(options))
+        end
+
+        # Appends a static Note (non-focusable).
+        def note(text, **options)
+          fields << Note.new(text, **field_options(options))
+        end
+
+        # Assembles the collected fields into a Form component, bound to *state* and using
+        # the *theme* argument (falling back to the builder's theme).
+        def build(state:, theme: nil)
+          Components::Form.new(fields: fields, state: state, theme: theme || self.theme)
+        end
+
+        private
+
+        # Merges the builder's theme into the per-field *options* so each field receives it.
+        def field_options(options)
+          {theme: theme}.merge(options)
         end
       end
     end

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

@@ -1,54 +1,65 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Components
-      class Form
-        class Confirm < Field
-          def initialize(name, value: false, **options)
-            super(name, **options)
-            @initial_value = value
-          end
+  module Components
+    class Form
+      # Confirm is a boolean Form field that renders a checkbox-style control. Space toggles
+      # the value; y/Right sets it to true; n/Left sets it to false. Required confirms must
+      # be accepted (value == true) to pass validation.
+      class Confirm < Field
+        # *value* is the initial boolean state (default: false). All other options are
+        # forwarded to Field.
+        def initialize(name, value: false, **options)
+          super(name, **options)
+          @initial_value = value
+        end
 
-          def handle_key(event)
-            case Charming.key_of(event)
-            when :space
-              toggle
-            when :y, :right
-              state[:values][name] = true
-            when :n, :left
-              state[:values][name] = false
-            else
-              return nil unless event.respond_to?(:char) && event.char == " "
-
-              toggle
-            end
-            :handled
+        # Handles the standard confirm keys: space toggles, y/right sets to true, n/left
+        # sets to false, and a space character (when the event exposes `char`) also toggles.
+        def handle_key(event)
+          case Charming.key_of(event)
+          when :space
+            toggle
+          when :y, :right
+            state[:values][name] = true
+          when :n, :left
+            state[:values][name] = false
+          else
+            return nil unless event.respond_to?(:char) && event.char == " "
+
+            toggle
           end
+          :handled
+        end
 
-          def validate
-            return ["must be accepted"] if required? && value != true
+        # Returns ["must be accepted"] when required and the value is not true, otherwise
+        # the result of the base Field validation.
+        def validate
+          return ["must be accepted"] if required? && value != true
 
-            super
-          end
+          super
+        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 render_control
-            "#{checked_marker} #{label}"
-          end
+        # Renders "[x] Label" or "[ ] Label" depending on the current value.
+        def render_control
+          "#{checked_marker} #{label}"
+        end
 
-          def checked_marker
-            value ? "[x]" : "[ ]"
-          end
+        # Returns the checkbox marker string.
+        def checked_marker
+          value ? "[x]" : "[ ]"
+        end
 
-          def toggle
-            state[:values][name] = !value
-          end
+        # Flips the current value (true ↔ false).
+        def toggle
+          state[:values][name] = !value
         end
       end
     end

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

@@ -1,94 +1,117 @@
 # 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
+  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
 
-          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
 
-          def focusable?
-            true
-          end
+        # Subclasses that participate in Tab/Enter navigation return true. Default is true.
+        def focusable?
+          true
+        end
 
-          def handle_key(_event)
-            nil
-          end
+        # Default key handler returns nil (no key handling). Subclasses override.
+        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
+        # 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
 
-          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
 
-          def value
-            state[:values][name]
-          end
+        # The current value of this field from the bound state.
+        def value
+          state[:values][name]
+        end
 
-          private
+        private
 
-          def default_value
-            nil
-          end
+        # The default value assigned to a freshly-bound field. Subclasses override.
+        def default_value
+          nil
+        end
 
-          def render_control
-            "#{label}: #{value}"
-          end
+        # Renders the control portion (label + value). Default: "Label: <value>".
+        def render_control
+          "#{label}: #{value}"
+        end
 
-          def required?
-            @required
-          end
+        # True when the field was declared with `required: true`.
+        def required?
+          @required
+        end
 
-          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
 
-          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
 
-          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
 
-          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
 
-          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,55 +1,67 @@
 # 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
+  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
+
+        # 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
+
+        private
+
+        # 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
+
+        # 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
       end
     end