charming 0.2.3 → 0.4.0

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

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

@@ -54,16 +54,25 @@ module Charming
         clamp_position
       end
 
-      # Handles key events. Returns `[:selected, item]` on Enter when an item is selected;
-      # otherwise delegates to the KeyboardHandler for navigation keys.
+      # Replaces the source items (e.g. after the underlying data changed) and
+      # reclamps the selection. Lets a memoized list stay fresh: keep the component
+      # in an ivar so its selection survives, then assign `list.items = rows`
+      # before each render.
+      def items=(new_items)
+        @source_items = new_items
+        clamp_position
+      end
+
+      # Handles key events. Returns `Result.selected(item)` on Enter when an item is
+      # selected; otherwise delegates to the KeyboardHandler for navigation keys.
       def handle_key(event)
-        return [:selected, selected_item] if Charming.key_of(event) == :enter && selected_item
+        return Result.selected(selected_item) if Charming.key_of(event) == :enter && selected_item
 
         super
       end
 
       # Handles mouse events: a click within the visible window selects the clicked row.
-      # Returns :handled on a successful click, nil otherwise.
+      # Returns Result.handled on a successful click, nil otherwise.
       def handle_mouse(event)
         return nil unless @height
         return nil unless event.respond_to?(:click?) && event.click?
@@ -73,7 +82,7 @@ module Charming
 
         @selected_index = viewport_start + clicked
         clamp_position
-        :handled
+        Result.handled
       end
 
       # Returns the currently selected item, or nil when the list is empty.

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

@@ -28,8 +28,9 @@ module Charming
         @style = style
       end
 
-      # Scrolls the body when it is taller than max_body_height. Returns :handled when the
-      # key moved the viewport, nil otherwise (so callers can route unconsumed keys).
+      # Scrolls the body when it is taller than max_body_height. Returns the Viewport's
+      # Result (Result.handled when the key scrolled), or nil when the modal is not
+      # scrollable (so callers can route unconsumed keys).
       def handle_key(event)
         return nil unless scrollable?
 

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

@@ -5,9 +5,9 @@ module Charming
     # MultiSelectList is a List variant where Space toggles per-item checkmarks and
     # Enter submits the checked set. Renders `[x]` / `[ ]` prefixes.
     #
-    # `handle_key` returns `[:submitted, [item, ...]]` on Enter, :handled for toggles
-    # and navigation, nil otherwise. *max_selections* optionally caps how many items
-    # can be checked at once.
+    # `handle_key` returns `Result.submitted([item, ...])` on Enter, Result.handled for
+    # toggles and navigation, nil otherwise. *max_selections* optionally caps how many
+    # items can be checked at once.
     class MultiSelectList < List
       # The set of selected (checked) item indices.
       attr_reader :selected_indices
@@ -20,11 +20,18 @@ module Charming
         @max_selections = max_selections
       end
 
+      # Replaces the items, reclamps the highlight (List#items=), and drops checks
+      # that fall outside the new list.
+      def items=(new_items)
+        super
+        @selected_indices = selected_indices.select { |index| index < items.length }
+      end
+
       # Space toggles the highlighted item, Enter submits the checked items.
       def handle_key(event)
         case Charming.key_of(event)
         when :space then toggle_current
-        when :enter then [:submitted, selected_items]
+        when :enter then Result.submitted(selected_items)
         else
           # Bypass List#handle_key (its Enter means single-select); use its navigation.
           keyboard_navigation(event)
@@ -52,11 +59,11 @@ module Charming
         if selected_indices.include?(index)
           selected_indices.delete(index)
         else
-          return :handled if @max_selections && selected_indices.length >= @max_selections
+          return Result.handled if @max_selections && selected_indices.length >= @max_selections
 
           selected_indices << index
         end
-        :handled
+        Result.handled
       end
 
       # Navigation via the KeyboardHandler key actions (up/down/home/end and keymap aliases).
@@ -66,7 +73,7 @@ module Charming
         return nil unless action
 
         send(action)
-        :handled
+        Result.handled
       end
 
       # One row: checkbox, then the labeled item; highlighted row in selected style.

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Result is what an interactive component returns from `handle_key`, `handle_mouse`,
+    # and `handle_paste`. `kind` is the event (:handled, :submitted, :selected,
+    # :cancelled, or :changed — changed is reserved for a future `on_change` DSL);
+    # `value` carries the payload for submit/select/change. The legacy return forms
+    # (:handled, :cancelled, [:submitted, value], [:selected, value]) still work —
+    # the dispatch collaborator normalizes them to Results with `Result.normalize`.
+    Result = Data.define(:kind, :value) do
+      class << self
+        # The component consumed the event; nothing to dispatch.
+        def handled = new(kind: :handled, value: nil)
+
+        # The component submitted a value (Enter on the last field, Ctrl+S).
+        def submitted(value) = new(kind: :submitted, value: value)
+
+        # The component selected an item (Enter/click on a row).
+        def selected(value) = new(kind: :selected, value: value)
+
+        # The component was dismissed (Escape).
+        def cancelled = new(kind: :cancelled, value: nil)
+
+        # Reserved: the component's value changed. No controller DSL consumes it yet.
+        def changed(value) = new(kind: :changed, value: value)
+
+        # Normalizes a legacy handle_* return value to a Result. nil and unknown
+        # values pass through.
+        def normalize(value)
+          case value
+          when Result then value
+          when :handled then handled
+          when :cancelled then cancelled
+          when Array then normalize_array(value)
+          else value
+          end
+        end
+
+        private
+
+        # Normalizes the legacy two-element array forms, [:submitted, v] and
+        # [:selected, v]. Unknown arrays pass through unchanged.
+        def normalize_array(value)
+          event, payload = value
+          return submitted(payload) if event == :submitted
+          return selected(payload) if event == :selected
+
+          value
+        end
+      end
+
+      # Kind predicates for the dispatch pipeline and the shell.
+      def handled? = kind == :handled
+      def submitted? = kind == :submitted
+      def selected? = kind == :selected
+      def cancelled? = kind == :cancelled
+      def changed? = kind == :changed
+    end
+  end
+end

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

@@ -8,8 +8,8 @@ module Charming
     #
     #   TabBar.new(tabs: ["Files", "Search", "Git"], selected_index: 0)
     #
-    # `handle_key` returns `[:selected, index]` on Enter, `:handled` for navigation keys,
-    # and nil otherwise.
+    # `handle_key` returns `Result.selected(index)` on Enter, Result.handled for
+    # navigation keys, and nil otherwise.
     class TabBar < Component
       include KeyboardHandler
 
@@ -24,6 +24,14 @@ module Charming
       # The tab labels and the index of the active tab.
       attr_reader :tabs, :selected_index
 
+      # Replaces the tab labels and reclamps the active tab. Lets a memoized tab bar
+      # stay fresh: keep the component in a slot and assign `bar.tabs = names` before
+      # each render.
+      def tabs=(new_tabs)
+        @tabs = Array(new_tabs).map(&:to_s)
+        @selected_index = @tabs.empty? ? 0 : selected_index.clamp(0, @tabs.length - 1)
+      end
+
       # *tabs* is the array of tab labels. *selected_index* is the active tab (default 0).
       # *separator* spaces the tabs apart.
       def initialize(tabs:, selected_index: 0, separator: "  ", keymap: :vim, theme: nil)
@@ -34,15 +42,15 @@ module Charming
         @keymap = keymap
       end
 
-      # Returns `[:selected, index]` on Enter; navigation keys move the active tab.
+      # Returns `Result.selected(index)` on Enter; navigation keys move the active tab.
       def handle_key(event)
         return nil if tabs.empty?
-        return [:selected, selected_index] if Charming.key_of(event) == :enter
+        return Result.selected(selected_index) if Charming.key_of(event) == :enter
 
         super
       end
 
-      # Selects the clicked tab. Returns :handled when a tab was hit, nil otherwise.
+      # Selects the clicked tab. Returns Result.handled when a tab was hit, nil otherwise.
       def handle_mouse(event)
         return nil if tabs.empty?
         return nil unless event.respond_to?(:click?) && event.click?
@@ -51,7 +59,7 @@ module Charming
         return nil unless index
 
         @selected_index = index
-        :handled
+        Result.handled
       end
 
       # Renders the tabs on one row, the active tab in the selected style.

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

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
-require "tty-table"
-
 module Charming
   module Components
     # Table renders tabular data with a header row, a selected row highlight, and keyboard
-    # navigation. Mouse clicks within the body area also select rows. The table is rendered
-    # via tty-table and the selected row is overlaid with reverse-video ANSI styling.
+    # navigation. Mouse clicks within the body area also select rows. The grid is drawn
+    # with Charming's own width/border machinery (square border chars plus junctions);
+    # the selected row is overlaid with reverse-video ANSI styling.
     class Table < Component
       include KeyboardHandler
 
@@ -42,20 +41,20 @@ module Charming
         @height = height
       end
 
-      # Handles key events. Returns `[:selected, row]` on Enter; otherwise delegates to the
-      # KeyboardHandler for navigation keys.
+      # Handles key events. Returns `Result.selected(row)` on Enter; otherwise delegates
+      # to the KeyboardHandler for navigation keys.
       def handle_key(event)
         return nil if rows.empty?
 
         case Charming.key_of(event)
-        when :enter then [:selected, selected_row]
+        when :enter then Result.selected(selected_row)
         else super
         end
       end
 
       # Handles mouse events: a click within the body area selects the clicked row
       # (relative to the visible window when a height is set).
-      # Returns :handled on a successful click.
+      # Returns Result.handled on a successful click.
       def handle_mouse(event)
         return nil if rows.empty?
         return nil unless event.respond_to?(:click?) && event.click?
@@ -64,7 +63,7 @@ module Charming
         return nil if clicked.negative? || clicked >= visible_row_count
 
         @selected_index = viewport_start + clicked
-        :handled
+        Result.handled
       end
 
       # Returns the currently selected row, or nil when the table is empty.
@@ -72,6 +71,15 @@ module Charming
         rows[selected_index]
       end
 
+      # Replaces the body rows (e.g. after the underlying data changed) and
+      # reclamps the selection. Lets a memoized table stay fresh: keep the component
+      # in an ivar so its selection survives, then assign `table.rows = rows`
+      # before each render.
+      def rows=(new_rows)
+        @rows = Array(new_rows)
+        @selected_index = clamp_index(selected_index)
+      end
+
       # Sorts the body rows by *column* (a header label or 0-based index).
       # Numeric-looking cells compare numerically; everything else as strings.
       # The sorted column is marked ▲/▼ in the rendered header. Returns self.
@@ -94,16 +102,57 @@ module Charming
       def render
         return "(empty table)" if header.empty? && rows.empty?
 
-        normalized = rows.map { |row| normalize_row(row) }
-        lines = TTY::Table.new(header: sort_marked_header, rows: normalized)
-          .render(:unicode)
-          .lines(chomp: true)
-
-        compact_layout(lines)
+        body = rows.map { |row| normalize_row(row) }
+        columns = [header.length, *body.map(&:length)].max
+        widths = column_widths(body, columns)
+        lines = [border_line(widths, grid.top_left, grid_top_junction, grid.top_right)]
+        lines << grid_line(marked_header_row(columns), widths) unless header.empty?
+        window = body[viewport_start, visible_row_count] || []
+        window.each_with_index do |cells, index|
+          line = grid_line(cells, widths)
+          lines << (((viewport_start + index) == selected_index) ? theme.selected.render(line) : line)
+        end
+        lines << border_line(widths, grid.bottom_left, grid_bottom_junction, grid.bottom_right)
+        lines.join("\n")
       end
 
       private
 
+      # The square border set the grid is drawn with.
+      def grid
+        UI::Border.fetch(:square)
+      end
+
+      # Column junction characters for the grid's top and bottom borders.
+      def grid_top_junction = "┬"
+
+      def grid_bottom_junction = "┴"
+
+      # The display width of each column: the widest cell or header label, measured
+      # with ANSI-aware display width so wide characters pad correctly.
+      def column_widths(body, columns)
+        lines = header.empty? ? body : [sort_marked_header, *body]
+        Array.new(columns) do |column|
+          UI::Width.widest(lines.map { |cells| cells[column].to_s })
+        end
+      end
+
+      # The header row padded out to *columns* cells (short rows render empty cells).
+      def marked_header_row(columns)
+        sort_marked_header + Array.new([columns - header.length, 0].max, "")
+      end
+
+      # One body/header line: cells padded to column width, joined by verticals.
+      def grid_line(cells, widths)
+        padded = widths.each_with_index.map { |width, index| UI::Width.pad_to(cells[index].to_s, width) }
+        "#{grid.vertical}#{padded.join(grid.vertical)}#{grid.vertical}"
+      end
+
+      # A top or bottom border line across the column widths.
+      def border_line(widths, left, junction, right)
+        "#{left}#{widths.map { |width| grid.horizontal * width }.join(junction)}#{right}"
+      end
+
       # Coerces a *row* (Hash / String / Array) into a flat cell array matching the header.
       # Excess cells are merged into the last column with a space separator.
       def normalize_row(row)
@@ -119,23 +168,6 @@ module Charming
         kept + [merged]
       end
 
-      # Applies the selected-row highlight, windows the body to the configured height,
-      # and trims unused body rows below the actual row count.
-      def compact_layout(lines)
-        return lines.join("\n") if lines.length < 4
-
-        top, header_line, _separator, *rest = lines
-        body = rest.first(rows.length)
-        bottom = rest[rows.length]
-
-        window = body[viewport_start, visible_row_count] || []
-        highlighted = window.each_with_index.map do |line, index|
-          ((viewport_start + index) == selected_index) ? theme.selected.render(line) : line
-        end
-
-        [top, header_line, *highlighted, bottom].compact.join("\n")
-      end
-
       # The top body row of the visible window (0 when no height is set), keeping the
       # selection in view.
       def viewport_start

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

@@ -37,12 +37,12 @@ module Charming
         true
       end
 
-      # Routes key events to the appropriate cursor/text mutation. Returns :handled when the
-      # event was consumed, nil otherwise.
+      # Routes key events to the appropriate cursor/text mutation. Returns Result.handled
+      # when the event was consumed, nil otherwise.
       def handle_key(event)
         key = Charming.key_of(event)
-        return :handled if newline_event?(event) && insert("\n")
-        return :handled if character_event?(event) && insert(event.char)
+        return Result.handled if newline_event?(event) && insert("\n")
+        return Result.handled if character_event?(event) && insert(event.char)
 
         case key
         when :left then move_left
@@ -58,15 +58,15 @@ module Charming
         else return nil
         end
 
-        :handled
+        Result.handled
       end
 
       # Inserts pasted text at the cursor. Newlines are preserved; other control
-      # characters (and CRLF carriage returns) are stripped. Returns :handled.
+      # characters (and CRLF carriage returns) are stripped. Returns Result.handled.
       def handle_paste(event)
         sanitized = event.text.to_s.tr("\r", "").gsub(/[^[:print:]\n]/, "")
         insert(sanitized) unless sanitized.empty?
-        :handled
+        Result.handled
       end
 
       # Renders the visible portion of the text buffer (scrolled to `offset`), with each

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

@@ -51,26 +51,26 @@ module Charming
       end
 
       # Handles key events. Inserts printable characters, submits on Enter
-      # (returning `[:submitted, value]` so a focused slot dispatches
+      # (returning `Result.submitted(value)` so a focused slot dispatches
       # `<slot>_submitted(value)`), recalls history on up/down (when enabled),
       # otherwise dispatches via KEY_ACTIONS.
-      # Returns :handled or `[:submitted, value]` when the event was consumed, nil otherwise.
+      # Returns Result.handled or Result.submitted(value) when the event was consumed, nil otherwise.
       def handle_key(event)
-        return :handled if character_event?(event) && insert(event.char)
+        return Result.handled if character_event?(event) && insert(event.char)
 
         key = Charming.key_of(event)
-        return [:submitted, value] if key == :enter
-        return :handled if history_event(key)
+        return Result.submitted(value) if key == :enter
+        return Result.handled if history_event(key)
 
         super
       end
 
       # Inserts pasted text at the cursor (newlines and control characters are
-      # stripped — this is a single-line input). Returns :handled.
+      # stripped — this is a single-line input). Returns Result.handled.
       def handle_paste(event)
         sanitized = event.text.to_s.gsub(/[[:cntrl:]]/, "")
         insert(sanitized) unless sanitized.empty?
-        :handled
+        Result.handled
       end
 
       # Renders the value with a cursor marker. When *width* was given at construction, the

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

@@ -6,8 +6,8 @@ module Charming
     # hashes: `{label: "src", children: [...], expanded: true}` — `children` and
     # `expanded` are optional. Navigation: up/down move the cursor through *visible*
     # nodes, right expands, left collapses (or jumps to the parent), Enter returns
-    # `[:selected, node]` for leaves and toggles branches. Mouse clicks move the cursor
-    # and toggle branches.
+    # `Result.selected(node)` for leaves and toggles branches. Mouse clicks move the
+    # cursor and toggle branches.
     class Tree < Component
       include KeyboardHandler
 
@@ -23,6 +23,15 @@ module Charming
       # The root node list and the cursor index into the visible-node list.
       attr_reader :nodes, :cursor_index
 
+      # Replaces the root nodes (e.g. after the underlying data changed) and reclamps
+      # the cursor. Expansion state lives in the node hashes, so fresh nodes render
+      # with the expansion they carry. Lets a memoized tree stay fresh: keep the
+      # component in a slot and assign `tree.nodes = rows` before each render.
+      def nodes=(new_nodes)
+        @nodes = new_nodes
+        clamp_cursor
+      end
+
       # *nodes* is the array of root node hashes (mutated in place to track expansion).
       # *height* optionally constrains the visible window.
       def initialize(nodes:, cursor_index: 0, height: nil, keymap: :vim, theme: nil)
@@ -34,7 +43,7 @@ module Charming
         clamp_cursor
       end
 
-      # Enter selects a leaf (`[:selected, node]`) or toggles a branch. Navigation keys
+      # Enter selects a leaf (`Result.selected(node)`) or toggles a branch. Navigation keys
       # are handled by KeyboardHandler.
       def handle_key(event)
         node = current_node
@@ -54,7 +63,7 @@ module Charming
         @cursor_index = clicked
         node = current_node
         toggle(node) if branch?(node)
-        :handled
+        Result.handled
       end
 
       # The node under the cursor (a node hash), or nil for an empty tree.
@@ -104,10 +113,10 @@ module Charming
       end
 
       def select_or_toggle(node)
-        return [:selected, node] unless branch?(node)
+        return Result.selected(node) unless branch?(node)
 
         toggle(node)
-        :handled
+        Result.handled
       end
 
       def toggle(node)