charming 0.1.0 → 0.1.2

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+
+          # 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
+
+          # 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
+
+          private
+
+          # The default value for a freshly-bound field is the *value* passed at construction.
+          def default_value
+            @initial_value
+          end
+
+          # Renders "[x] Label" or "[ ] Label" depending on the current value.
+          def render_control
+            "#{checked_marker} #{label}"
+          end
+
+          # Returns the checkbox marker string.
+          def checked_marker
+            value ? "[x]" : "[ ]"
+          end
+
+          # Flips the current value (true ↔ false).
+          def toggle
+            state[:values][name] = !value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# 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
+
+          # 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
+
+          # 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
+
+          # 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
+
+          private
+
+          # 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
+
+          # 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)
+
+            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
+          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
+
+          # Converts a snake_case symbol/string to a humanized "Capitalized" string.
+          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,71 @@
+# 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
+
+          # 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
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# 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
+
+          # 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 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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# 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
+
+          # 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
+
+            save_selection(selection.selected_index)
+            :handled
+          end
+
+          private
+
+          # 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
+
+          # 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
+
+          # 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
+          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
+
+          # 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?
+
+            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 per-field state hash for this field.
+          def field_state
+            state[:fields][name]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+
+          # 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
+
+          # 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
+
+          # 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
+
+          # The default value for a freshly-bound field is the *value* passed at construction.
+          def default_value
+            @initial_value
+          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
+
+          # 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
+
+          # Returns the per-field state hash for this field.
+          def field_state
+            state[:fields][name]
+          end
+        end
+      end
+    end
+  end
+end