charming 0.3.0 → 0.4.0

data/lib/charming/generators/view_generator.rb

@@ -40,7 +40,7 @@ module Charming
 
       # CamelCase rendering of the action name (e.g., "user_settings" → "UserSettings").
       def action_class_name
-        ActiveSupport::Inflector.camelize(action)
+        Internal::Inflections.camelize(action)
       end
     end
   end

data/lib/charming/internal/deep_freeze.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    # DeepFreeze returns a deep-frozen copy of a value: strings, arrays, hashes, and
+    # sets are duplicated (recursively) and frozen; numbers, symbols, and nil pass
+    # through as-is (already immutable); anything else (IO, models, components) passes
+    # through unfrozen — it has no sane freeze semantics across a thread boundary.
+    # The caller's originals are never frozen.
+    module DeepFreeze
+      # Returns a deep-frozen copy of *value* per the rules above.
+      def self.call(value)
+        case value
+        when Hash then value.to_h { |key, element| [call(key), call(element)] }.freeze
+        when Array then value.map { |element| call(element) }.freeze
+        when Set then value.map { |element| call(element) }.to_set.freeze
+        when String then value.frozen? ? value : value.dup.freeze
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/env_inquirer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    # A String that answers predicates about its own value:
+    # `EnvInquirer.new("development").development?` → true. Replaces
+    # ActiveSupport::StringInquirer for `Charming.env`.
+    class EnvInquirer < String
+      private
+
+      def method_missing(name, *)
+        return self == name.to_s.delete_suffix("?") if name.end_with?("?")
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        name.end_with?("?") || super
+      end
+    end
+  end
+end

data/lib/charming/internal/inflections.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    # String inflection helpers covering exactly what Charming needs, with
+    # ActiveSupport-compatible semantics for the inputs Charming produces
+    # (snake_case identifiers and "A::B" constant paths). Replaces the former
+    # ActiveSupport::Inflector dependency. `pluralize` implements a deliberate
+    # subset of English rules — enough for conventional resource names — not
+    # ActiveSupport's full inflection table.
+    module Inflections
+      module_function
+
+      # "weather_report" → "WeatherReport"; "admin/users" → "Admin::Users".
+      def camelize(term)
+        string = term.to_s.sub(/\A[a-z\d]*/, &:capitalize)
+        string.gsub(%r{(?:_|(/))([a-z\d]*)}i) { "#{Regexp.last_match(1) && "::"}#{Regexp.last_match(2).capitalize}" }
+      end
+
+      # "HomeController" → "home_controller"; "MyApp::Home" → "my_app/home";
+      # acronym runs get a boundary before a capitalized word ("HTMLTidy" → "html_tidy").
+      def underscore(camel_cased_word)
+        word = camel_cased_word.to_s.gsub("::", "/")
+        word.gsub!(/([A-Z\d]+)(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) { "#{Regexp.last_match(1) || Regexp.last_match(2)}_" }
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+
+      # "MyApp::HomeController" → "HomeController".
+      def demodulize(path)
+        path.to_s.split("::").last
+      end
+
+      # "MyApp::Application" → "MyApp"; "Application" → "".
+      def deconstantize(path)
+        path.to_s[0, path.to_s.rindex("::") || 0]
+      end
+
+      # "Charming::Router" → Charming::Router. Raises NameError on a miss.
+      def constantize(name)
+        Object.const_get(name)
+      end
+
+      # "user_name" → "User name"; "author_id" → "Author". Assumes snake_case input.
+      def humanize(lower_case_and_underscored_word)
+        result = lower_case_and_underscored_word.to_s.sub(/_id\z/, "").tr("_", " ")
+        result.sub(/\A\w/, &:upcase)
+      end
+
+      # "category" → "categories"; "person" → "people". A subset of English
+      # rules covering conventional resource names; exotic words may need the
+      # generated migration renamed by hand.
+      def pluralize(word)
+        result = word.to_s.dup
+        return result if UNCOUNTABLE.include?(result)
+
+        irregular = IRREGULAR_FORMS[result.split("_").last]
+        return result.sub(/[^_]+\z/, irregular) if irregular
+
+        PLURAL_RULES.each do |pattern, replacement|
+          return result.sub(pattern, replacement) if result.match?(pattern)
+        end
+        result
+      end
+
+      IRREGULAR_FORMS = {
+        "child" => "children",
+        "man" => "men",
+        "mouse" => "mice",
+        "person" => "people",
+        "sex" => "sexes",
+        "woman" => "women"
+      }.freeze
+
+      UNCOUNTABLE = %w[equipment information money rice series sheep species].freeze
+
+      # Ordered: the first matching rule wins. Mirrors the head of
+      # ActiveSupport's plural rule list for the inputs generators produce.
+      PLURAL_RULES = [
+        [/(quiz)\z/, '\1zes'],
+        [/(matr|vert|ind)(ix|ex)\z/, '\1ices'],
+        [/(x|ch|ss|sh)\z/, '\1es'],
+        [/([^aeiouy]|qu)y\z/, '\1ies'],
+        [/sis\z/, "ses"],
+        [/([ti])um\z/, '\1a'],
+        [/(buffal|tomat|potat|her)o\z/, '\1oes'],
+        [/s\z/, "s"],
+        [/\z/, "s"]
+      ].freeze
+    end
+  end
+end

data/lib/charming/internal/session_guard.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Charming
+  module Internal
+    # SessionGuard wraps the application session hash and asserts every access happens
+    # on the controller's loop thread. Controller#session returns this wrapper in
+    # development and test; production gets the raw hash (a warning is logged instead
+    # of a raise).
+    class SessionGuard < SimpleDelegator
+      def initialize(session, controller)
+        super(session)
+        @controller = controller
+      end
+
+      def method_missing(name, *args, &block)
+        @controller.assert_loop_thread!(:session)
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        __getobj__.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/cursor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Terminal
+      # Cursor emits the ANSI escape sequences for cursor visibility, screen clearing,
+      # and positioning. Replaces tty-cursor (a stateless escape-string generator) with
+      # the four sequences TTYBackend actually uses, asserted byte-for-byte in
+      # spec/internal/terminal/cursor_spec.rb.
+      module Cursor
+        module_function
+
+        # Shows the terminal cursor (DECTCEM set).
+        def show = "\e[?25h"
+
+        # Hides the terminal cursor (DECTCEM reset).
+        def hide = "\e[?25l"
+
+        # Clears the whole screen (ED 2).
+        def clear_screen = "\e[2J"
+
+        # Moves the cursor to zero-based *column*/*row* (CUP is one-based row;column).
+        def move_to(column, row)
+          "\e[#{row + 1};#{column + 1}H"
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/size.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Terminal
+      # Size detects terminal dimensions without tty-screen: IO#winsize on the first
+      # reporting IO (a TTY), then ENV["COLUMNS"]/ENV["LINES"], then the 80x24 default.
+      module Size
+        DEFAULT_SIZE = [80, 24].freeze
+
+        module_function
+
+        # Returns [width, height] for the first of *ios* that reports a winsize,
+        # falling back to the environment and then the default.
+        def measure(*ios, env: ENV)
+          ios.each do |io|
+            size = winsize(io)
+            return size if size
+          end
+          env_size(env) || DEFAULT_SIZE
+        end
+
+        # IO#winsize reports [rows, columns]; size is [width, height]. Nil for IOs
+        # without a size (StringIO, pipes, closed streams).
+        def winsize(io)
+          return nil unless io.respond_to?(:winsize)
+
+          rows, columns = io.winsize
+          return nil if rows.to_i.zero? || columns.to_i.zero?
+
+          [columns, rows]
+        rescue SystemCallError, IOError
+          nil
+        end
+
+        # The COLUMNS/LINES environment size, or nil when either is unset or zero.
+        def env_size(env)
+          columns = env["COLUMNS"].to_i
+          lines = env["LINES"].to_i
+          return nil if columns.zero? || lines.zero?
+
+          [columns, lines]
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/tty_backend.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-require "tty-cursor"
+require "io/console"
 require "tty-reader"
-require "tty-screen"
 
 module Charming
   module Internal
     module Terminal
       # TTYBackend is the production terminal backend. It reads key and mouse events from
       # a TTY::Reader, normalizes them via KeyNormalizer and MouseParser, and writes output
-      # frames using TTY::Cursor and TTY::Screen. It also installs SIGWINCH and SIGINFO
-      # handlers so the runtime can react to terminal resize and focus changes.
+      # frames using Terminal::Cursor sequences and IO#winsize for dimensions. It also
+      # installs SIGWINCH and SIGINFO handlers so the runtime can react to terminal resize
+      # and focus changes.
       class TTYBackend
         include Adapter
 
@@ -37,8 +37,9 @@ module Charming
 
         # *input* and *output* default to `$stdin`/`$stdout` for normal terminal use;
         # tests can inject IO objects. *reader* is a TTY::Reader instance (created from
-        # *input*/*output* when nil). *cursor* is the TTY::Cursor class used for cursor control.
-        def initialize(input: $stdin, output: $stdout, reader: nil, cursor: TTY::Cursor)
+        # *input*/*output* when nil). *cursor* is the Terminal::Cursor module used for
+        # cursor control sequences.
+        def initialize(input: $stdin, output: $stdout, reader: nil, cursor: Cursor)
           @input = input
           @output = output
           @reader = reader || TTY::Reader.new(input: input, output: output)
@@ -274,8 +275,9 @@ module Charming
           write_control(@cursor.move_to(column - 1, row - 1))
         end
 
-        # Returns the current terminal dimensions as [width, height] via TTY::Screen.
-        def size = [TTY::Screen.width, TTY::Screen.height]
+        # Returns the current terminal dimensions as [width, height]: IO#winsize on the
+        # output/input streams, then COLUMNS/LINES, then 80x24.
+        def size = Size.measure(@output, @input)
 
         private
 

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

@@ -9,8 +9,8 @@ module Charming
     #
     #   Autocomplete.new(suggestions: ["ruby", "rails", "rspec"], value: "r")
     #
-    # `handle_key` returns `[:submitted, value]` on Enter, `:cancelled` on Escape,
-    # `:handled` for consumed keys, nil otherwise.
+    # `handle_key` returns `Result.submitted(value)` on Enter, `Result.cancelled` on
+    # Escape, `Result.handled` for consumed keys, nil otherwise.
     class Autocomplete < Component
       DEFAULT_MAX_SUGGESTIONS = 6
 
@@ -29,6 +29,14 @@ module Charming
         clamp_selection
       end
 
+      # Replaces the suggestion list and reclamps the selection against the filtered
+      # list. Lets a memoized autocomplete stay fresh: keep the component in a slot
+      # and assign `combo.suggestions = names` before each render.
+      def suggestions=(new_suggestions)
+        @suggestions = Array(new_suggestions).map(&:to_s)
+        clamp_selection
+      end
+
       # The typed text.
       def value
         @input.value
@@ -56,8 +64,8 @@ module Charming
       # edits the text (resetting the highlight).
       def handle_key(event)
         case Charming.key_of(event)
-        when :escape then :cancelled
-        when :enter then [:submitted, submission_value]
+        when :escape then Result.cancelled
+        when :enter then Result.submitted(submission_value)
         when :up then move_selection(-1)
         when :down then move_selection(+1)
         else
@@ -100,10 +108,10 @@ module Charming
 
       def move_selection(delta)
         count = filtered_suggestions.length
-        return :handled if count.zero?
+        return Result.handled if count.zero?
 
         @selected_index = (selected_index + delta).clamp(0, count - 1)
-        :handled
+        Result.handled
       end
 
       def clamp_selection

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

@@ -5,7 +5,8 @@ module Charming
     # CommandPalette renders a fuzzy-searchable command picker UI. It wraps a TextInput for search
     # input and a List for result display, dispatching key events between them. Users type to filter
     # the registered commands by label match, navigate with up/down/home/end keys (delegated to List),
-    # confirm a selection with Enter (returns [:selected, command]), or cancel with Escape (returns :cancelled).
+    # confirm a selection with Enter (returns Result.selected(command)), or cancel with Escape (returns
+    # Result.cancelled).
     # State is serializable as a hash of value/cursor/selected_index for session persistence.
     class CommandPalette < Component
       Command = Data.define(:label, :value)
@@ -49,14 +50,14 @@ module Charming
       end
 
       # Handles key events by routing them to the appropriate sub-component: Escape kills the
-      # palette returning :cancelled; up/down/home/end keys go to the List selection handler
+      # palette returning Result.cancelled; up/down/home/end keys go to the List selection handler
       # via handle_list_key; all other keys (including typed characters) are passed to the TextInput
       # which manages cursor position and input filtering. If a list key match fails, falls through
-      # to the TextInput handler. Returns nil/nil if no handler consumed the event, or :cancelled when
-      # Escape is pressed.
+      # to the TextInput handler. Returns nil if no handler consumed the event, or Result.cancelled
+      # when Escape is pressed.
       def handle_key(event)
         key = Charming.key_of(event)
-        return :cancelled if key == :escape
+        return Result.cancelled if key == :escape
 
         return handle_list_key(event) if list_key?(key)
 
@@ -75,17 +76,18 @@ module Charming
       attr_reader :height, :list
 
       # Delegates key handling entirely to the internal List widget, which manages up/down/home/end selection.
-      # Returns whatever the List's handle_key returns (typically nil or the symbol from the subclass).
+      # Returns whatever the List's handle_key returns (a Result or nil).
       def handle_list_key(event)
         list.handle_key(event)
       end
 
       # Passes the key event to the TextInput for cursor position and search text management.
-      # If the input returns :handled, rebuilds the List so that filtering is re-evaluated against
-      # the new input value. Returns nil/nil if no handler consumed the event.
+      # If the input returns Result.handled, rebuilds the List so that filtering is re-evaluated
+      # against the new input value. Returns the input's Result, or nil when it did not consume
+      # the event.
       def handle_input_key(event)
         result = input.handle_key(event)
-        @list = build_list if result == :handled
+        @list = build_list if result&.handled?
         result
       end
 

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

@@ -3,7 +3,7 @@
 module Charming
   module Components
     # Filepicker is a directory browser built on List. Enter descends into the
-    # highlighted directory or returns `[:selected, absolute_path]` for a file;
+    # highlighted directory or returns `Result.selected(absolute_path)` for a file;
     # Backspace (or the "../" entry) goes up, never above the configured root.
     # Dotfiles are hidden until `toggle_hidden`.
     class Filepicker < Component
@@ -63,14 +63,14 @@ module Charming
         return ascend if entry == PARENT_ENTRY
         return descend(entry.delete_suffix("/")) if entry.end_with?("/")
 
-        [:selected, File.join(current_dir, entry)]
+        Result.selected(File.join(current_dir, entry))
       end
 
       # Enters *name* under the current directory.
       def descend(name)
         @current_dir = File.join(current_dir, name)
         rebuild_list
-        :handled
+        Result.handled
       end
 
       # Moves to the parent directory, unless already at the root.
@@ -79,7 +79,7 @@ module Charming
 
         @current_dir = File.dirname(current_dir)
         rebuild_list
-        :handled
+        Result.handled
       end
 
       # Builds a fresh List over the current directory's entries.

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

@@ -16,6 +16,7 @@ module Charming
 
         # 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.
+        # Returns Result.handled when consumed, nil otherwise.
         def handle_key(event)
           case Charming.key_of(event)
           when :space
@@ -29,7 +30,7 @@ module Charming
 
             toggle
           end
-          :handled
+          Result.handled
         end
 
         # Returns ["must be accepted"] when required and the value is not true, otherwise

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

@@ -116,7 +116,7 @@ module Charming
 
         # Converts a snake_case symbol/string to a humanized "Capitalized" string.
         def humanize(value)
-          ActiveSupport::Inflector.humanize(value)
+          Internal::Inflections.humanize(value)
         end
       end
     end

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

@@ -25,7 +25,7 @@ module Charming
         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.
+        # back into the form state. Returns Result.handled when the event was consumed.
         def handle_key(event)
           forward_to_input(:handle_key, event)
         end
@@ -41,11 +41,11 @@ module Charming
         # the event, persists the resulting value and cursor into the form state.
         def forward_to_input(message, event)
           text_input = input
-          return nil unless text_input.public_send(message, event) == :handled
+          return nil unless text_input.public_send(message, event)&.handled?
 
           state[:values][name] = text_input.value
           field_state[:cursor] = text_input.cursor
-          :handled
+          Result.handled
         end
 
         # The default value for a freshly-bound field is the *value* passed at construction.

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

@@ -27,16 +27,15 @@ module Charming
         end
 
         # Forwards key events to the underlying MultiSelectList, syncing the checked
-        # set and highlight cursor back into the field state. Returns :handled when
-        # consumed; Enter (the list's submit) is left unconsumed for the Form.
+        # set and highlight cursor back into the field state. Returns Result.handled when
+        # consumed; Enter (the list's Result.submitted) is left unconsumed for the Form.
         def handle_key(event)
           widget = list
           result = widget.handle_key(event)
-          return nil if result.is_a?(Array)
-          return nil unless result == :handled
+          return nil unless result&.handled?
 
           save_selection(widget)
-          :handled
+          Result.handled
         end
 
         private

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

@@ -24,14 +24,14 @@ module Charming
         end
 
         # Forwards key events to the underlying List, syncing the chosen option index back
-        # into the field state. Returns :handled when consumed.
+        # into the field state. Returns Result.handled when consumed.
         def handle_key(event)
           selection = list
           result = selection.handle_key(event)
-          return nil unless result == :handled
+          return nil unless result&.handled?
 
           save_selection(selection.selected_index)
-          :handled
+          Result.handled
         end
 
         private

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

@@ -27,7 +27,7 @@ module Charming
         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.
+        # and preferred column back into the form state. Returns Result.handled when consumed.
         def handle_key(event)
           forward_to_text_area(:handle_key, event)
         end
@@ -51,13 +51,13 @@ module Charming
         # event, persists the value, cursor, offset, and preferred column into form state.
         def forward_to_text_area(message, event)
           area = text_area
-          return nil unless area.public_send(message, event) == :handled
+          return nil unless area.public_send(message, event)&.handled?
 
           state[:values][name] = area.value
           field_state[:cursor] = area.cursor
           field_state[:offset] = area.offset
           field_state[:preferred_column] = area.preferred_column
-          :handled
+          Result.handled
         end
 
         # The default value for a freshly-bound field is the *value* passed at construction.

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

@@ -28,7 +28,7 @@ module Charming
       # 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 Result.cancelled if key == :escape
         return submit if submit_shortcut?(event)
         return move_focus(tab_direction(event)) if key == :tab
 
@@ -103,14 +103,14 @@ module Charming
         move_focus(+1)
       end
 
-      # Validates all fields, focuses the first invalid one, and returns [:submitted, values]
-      # when there are no errors.
+      # Validates all fields, focuses the first invalid one, and returns
+      # Result.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?
+        return Result.handled unless state[:errors].empty?
 
-        [:submitted, values.dup]
+        Result.submitted(values.dup)
       end
 
       # Runs each field's validator and collects per-field error messages.
@@ -139,7 +139,7 @@ module Charming
 
         current = indices.index(state[:focus_index]) || 0
         state[:focus_index] = indices[(current + direction) % indices.length]
-        :handled
+        Result.handled
       end
 
       # True when the current focus index is the last focusable field.

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

@@ -11,7 +11,7 @@ module Charming
     #
     #   HelpOverlay.new(bindings: {"q" => "Quit", "ctrl+p" => "Command palette"})
     #
-    # Any key dismisses it (`handle_key` returns :cancelled).
+    # Any key dismisses it (`handle_key` returns Result.cancelled).
     class HelpOverlay < Component
       DEFAULT_TITLE = "Keyboard Shortcuts"
       DEFAULT_WIDTH = 44
@@ -40,7 +40,7 @@ module Charming
 
       # Any key dismisses the overlay.
       def handle_key(_event)
-        :cancelled
+        Result.cancelled
       end
 
       # Renders the bindings table inside a titled modal.

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

@@ -6,8 +6,8 @@ module Charming
     # 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.
+    # looks up the corresponding action in KEY_ACTIONS, sends that method on self, and returns Result.handled
+    # if an action was found. Returns nil when no matching key exists.
     module KeyboardHandler
       VIM_KEYMAP = {
         up: :k,
@@ -22,7 +22,7 @@ module Charming
         return unless action
 
         send(action)
-        :handled
+        Result.handled
       end
 
       private