charming 0.2.0 → 0.2.1

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

@@ -2,10 +2,11 @@
 
 module Charming
   module Components
-    # TextArea is a multi-line text editor component. Supports character insertion (with
-    # newline insertion via Shift+Enter or Ctrl+J), cursor movement (left/right/up/down,
-    # home/end, page up/down), deletion (backspace/delete), and scrolling for long buffers.
-    # Vertical movement preserves a "preferred column" so left/right navigation feels stable.
+    # TextArea is a multi-line text editor component. Supports character insertion, newline
+    # insertion (plain Enter by default, plus Shift+Enter/Ctrl+J/Ctrl+N), cursor movement
+    # (left/right/up/down, home/end, page up/down), deletion (backspace/delete), and scrolling
+    # for long buffers. Vertical movement preserves a "preferred column" so left/right
+    # navigation feels stable.
     class TextArea < Component
       # The current text value, cursor byte offset, top-visible row offset, and remembered
       # column for vertical navigation, respectively.
@@ -15,7 +16,9 @@ module Charming
       # *height* constrain the rendered output. *cursor* defaults to the end of the value.
       # *offset* is the top-visible row. *preferred_column* is the column to resume at on
       # vertical movement (defaults to the current column on first use).
-      def initialize(value: "", placeholder: "", width: nil, height: nil, cursor: nil, offset: 0, preferred_column: nil)
+      # *enter_newline* (default true) makes plain Enter insert a newline — set false when a
+      # host widget wants Enter for itself (the key then falls through unhandled).
+      def initialize(value: "", placeholder: "", width: nil, height: nil, cursor: nil, offset: 0, preferred_column: nil, enter_newline: true)
         super()
         @value = value.dup
         @placeholder = placeholder
@@ -24,10 +27,16 @@ module Charming
         @cursor = cursor || @value.length
         @offset = offset
         @preferred_column = preferred_column
+        @enter_newline = enter_newline
         clamp_position
         ensure_cursor_visible
       end
 
+      # Free-typed characters belong to this component while it is focused.
+      def captures_text?
+        true
+      end
+
       # Routes key events to the appropriate cursor/text mutation. Returns :handled when the
       # event was consumed, nil otherwise.
       def handle_key(event)
@@ -52,6 +61,14 @@ module Charming
         :handled
       end
 
+      # Inserts pasted text at the cursor. Newlines are preserved; other control
+      # characters (and CRLF carriage returns) are stripped. Returns :handled.
+      def handle_paste(event)
+        sanitized = event.text.to_s.tr("\r", "").gsub(/[^[:print:]\n]/, "")
+        insert(sanitized) unless sanitized.empty?
+        :handled
+      end
+
       # Renders the visible portion of the text buffer (scrolled to `offset`), with each
       # visible line either clipped to `width` or padded to it.
       def render
@@ -62,11 +79,17 @@ module Charming
 
       attr_reader :placeholder, :width, :height
 
-      # True when the event represents an explicit newline request: Shift+Enter or Ctrl+J.
+      # True when the event represents a newline request. Plain Enter inserts a newline
+      # by default (the natural expectation in a text editor); Shift+Enter, Ctrl+J, and
+      # Ctrl+N always work, even when `enter_newline: false` reserves plain Enter for the
+      # host widget. (Shift+Enter is indistinguishable from Enter in many terminals, so
+      # Ctrl+N remains the TTY-safe fallback in that mode.)
       def newline_event?(event)
         key = Charming.key_of(event)
+        return true if key == :enter && @enter_newline
         return true if key == :enter && event.respond_to?(:shift) && event.shift
         return true if key == :j && event.respond_to?(:ctrl) && event.ctrl
+        return true if key == :n && event.respond_to?(:ctrl) && event.ctrl
 
         false
       end
@@ -162,12 +185,13 @@ module Charming
       end
 
       # Moves the cursor vertically by *delta* rows. Stays within the line count and uses
-      # `preferred_column` so up/down movement feels stable on short lines.
+      # `preferred_column` (in display columns) so up/down movement feels stable on short lines.
       def move_vertical(delta)
         row, column = cursor_position
         target_row = (row + delta).clamp(0, lines.length - 1)
         @preferred_column ||= column
-        @cursor = line_start(target_row) + [@preferred_column, line_length(target_row)].min
+        target_line = lines.fetch(target_row, "")
+        @cursor = line_start(target_row) + char_offset_at_display_col(target_line, @preferred_column)
         ensure_cursor_visible
       end
 
@@ -177,12 +201,14 @@ module Charming
       end
 
       # Returns the cursor's current position as `[row, column]`, where row is the zero-based
-      # line index and column is the character offset within that line.
+      # line index and column is the *display-column* offset within that line (wide characters
+      # such as emoji or CJK occupy two display columns each).
       def cursor_position
         before = value[0...cursor].to_s
         row = before.count("\n")
         last_newline = before.rindex("\n")
-        column = last_newline ? before.length - last_newline - 1 : before.length
+        line_before_cursor = last_newline ? before[(last_newline + 1)..] : before
+        column = UI::Width.measure(line_before_cursor)
         [row, column]
       end
 
@@ -196,6 +222,17 @@ module Charming
         lines.fetch(row, "").length
       end
 
+      # Returns the character offset within *line* where the display column reaches *display_col*.
+      # Stops at the last character when the line is shorter than *display_col*.
+      def char_offset_at_display_col(line, display_col)
+        col = 0
+        line.each_char.with_index do |char, idx|
+          return idx if col >= display_col
+          col += UI::Width.measure(char)
+        end
+        line.length
+      end
+
       # Splits the value into an array of lines (preserving trailing empty lines).
       def lines
         value.empty? ? [""] : value.split("\n", -1)

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

@@ -6,6 +6,10 @@ module Charming
     # cursor movement (left/right/home/end), and deletion (backspace/delete). The component
     # exposes its `value` and `cursor` positions as reader methods; when an explicit `width:`
     # is given, the rendered output is padded to that width via a UI::Style.
+    #
+    # Options:
+    # - `masked: true` renders every character as `*` (password entry)
+    # - `history: [...]` enables REPL-style recall — up/down cycle through prior values
     class TextInput < Component
       include KeyboardHandler
 
@@ -26,23 +30,44 @@ module Charming
 
       # *value* is the initial text. *placeholder* is shown when the value is empty.
       # *width* optionally constrains the rendered output width; *cursor* defaults to the end.
-      def initialize(value: "", placeholder: "", width: nil, cursor: nil)
+      # *masked* renders characters as `*`. *history* is an array of prior values cycled
+      # with up/down (most recent last, like a shell).
+      def initialize(value: "", placeholder: "", width: nil, cursor: nil, masked: false, history: nil)
         super()
         @value = value.dup
         @placeholder = placeholder
         @width = width
         @cursor = cursor || @value.length
+        @masked = masked
+        @history = history
+        @history_index = nil
+        @draft = nil
         clamp_position
       end
 
-      # Handles key events. Inserts printable characters, otherwise dispatches via KEY_ACTIONS.
+      # Free-typed characters belong to this component while it is focused.
+      def captures_text?
+        true
+      end
+
+      # Handles key events. Inserts printable characters, recalls history on up/down
+      # (when enabled), otherwise dispatches via KEY_ACTIONS.
       # Returns :handled when the event was consumed, nil otherwise.
       def handle_key(event)
         return :handled if character_event?(event) && insert(event.char)
+        return :handled if history_event(Charming.key_of(event))
 
         super
       end
 
+      # Inserts pasted text at the cursor (newlines and control characters are
+      # stripped — this is a single-line input). Returns :handled.
+      def handle_paste(event)
+        sanitized = event.text.to_s.gsub(/[[:cntrl:]]/, "")
+        insert(sanitized) unless sanitized.empty?
+        :handled
+      end
+
       # Renders the value with a cursor marker. When *width* was given at construction, the
       # output is padded to that width via the configured style.
       def render
@@ -105,12 +130,62 @@ module Charming
         @value = value[0...cursor] + value[(cursor + 1)..]
       end
 
+      # Cycles through history on :up / :down. Returns true when the event was consumed.
+      def history_event(key)
+        return false unless @history && !@history.empty?
+
+        case key
+        when :up then recall_previous
+        when :down then recall_next
+        else false
+        end
+      end
+
+      # Steps back through history (saving the in-progress draft first).
+      def recall_previous
+        if @history_index.nil?
+          @draft = value
+          @history_index = @history.length - 1
+        elsif @history_index.positive?
+          @history_index -= 1
+        end
+        replace_value(@history[@history_index])
+        true
+      end
+
+      # Steps forward through history; past the newest entry restores the draft.
+      def recall_next
+        return false if @history_index.nil?
+
+        @history_index += 1
+        if @history_index >= @history.length
+          @history_index = nil
+          replace_value(@draft.to_s)
+        else
+          replace_value(@history[@history_index])
+        end
+        true
+      end
+
+      # Replaces the value and moves the cursor to the end.
+      def replace_value(new_value)
+        @value = new_value.dup
+        @cursor = @value.length
+      end
+
       # Renders the value with a "|" cursor marker at the current position. When the value is
-      # empty, the placeholder is rendered instead, preceded by the cursor marker.
+      # empty, the placeholder is rendered instead, preceded by the cursor marker. Masked
+      # inputs render `*` per character.
       def render_value
         return cursor_marker + placeholder if value.empty?
 
-        value[0...cursor] + cursor_marker + value[cursor..]
+        shown = display_value
+        shown[0...cursor] + cursor_marker + shown[cursor..]
+      end
+
+      # The value as displayed: masked inputs substitute `*` for every character.
+      def display_value
+        @masked ? "*" * value.length : value
       end
 
       # The literal character used to mark the cursor position in `render`.

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Toast is a small auto-dismissing notification panel, usually composited as an
+    # overlay anchored to a screen corner. Controllers manage its lifetime with the
+    # `show_toast` / `dismiss_toast` helpers (which pair it with a timer); the component
+    # itself just renders the styled box.
+    #
+    #   Toast.new(message: "Saved!", kind: :success)
+    #
+    # *kind* picks the accent style: :info (default), :success, :warn, or :error.
+    class Toast < Component
+      KINDS = %i[info success warn error].freeze
+
+      attr_reader :message, :kind
+
+      # *message* is the toast text. *kind* is the visual accent. *width* optionally
+      # fixes the box width (otherwise it hugs the message).
+      def initialize(message:, kind: :info, width: nil, theme: nil)
+        super(theme: theme)
+        @message = message.to_s
+        @kind = KINDS.include?(kind) ? kind : :info
+        @width = width
+      end
+
+      # Renders the bordered toast box with a kind-colored border.
+      def render
+        box(message, style: toast_style)
+      end
+
+      private
+
+      # A rounded-border box accented by the kind's theme style.
+      def toast_style
+        base = style.border(:rounded, foreground: accent_color).padding(0, 1)
+        @width ? base.width(@width) : base
+      end
+
+      # Maps the kind to a border color: info/cyan-ish, success/green, warn/yellow, error/red.
+      def accent_color
+        case kind
+        when :success then :green
+        when :warn then :yellow
+        when :error then :red
+        else :cyan
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Tree renders a collapsible hierarchy (file explorers, nested data). Nodes are
+    # 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.
+    class Tree < Component
+      include KeyboardHandler
+
+      KEY_ACTIONS = {
+        up: :move_up,
+        down: :move_down,
+        left: :collapse_or_parent,
+        right: :expand,
+        home: :move_home,
+        end: :move_end
+      }.freeze
+
+      # The root node list and the cursor index into the visible-node list.
+      attr_reader :nodes, :cursor_index
+
+      # *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)
+        super(theme: theme)
+        @nodes = nodes
+        @cursor_index = cursor_index
+        @height = height
+        @keymap = keymap
+        clamp_cursor
+      end
+
+      # Enter selects a leaf (`[:selected, node]`) or toggles a branch. Navigation keys
+      # are handled by KeyboardHandler.
+      def handle_key(event)
+        node = current_node
+        return nil unless node
+        return select_or_toggle(node) if Charming.key_of(event) == :enter
+
+        super
+      end
+
+      # A click moves the cursor to the clicked row; clicking a branch toggles it.
+      def handle_mouse(event)
+        return nil unless event.respond_to?(:click?) && event.click?
+
+        clicked = viewport_start + event.y
+        return nil if clicked >= visible_nodes.length || event.y.negative?
+
+        @cursor_index = clicked
+        node = current_node
+        toggle(node) if branch?(node)
+        :handled
+      end
+
+      # The node under the cursor (a node hash), or nil for an empty tree.
+      def current_node
+        visible_nodes[cursor_index]&.fetch(:node)
+      end
+
+      # Renders the visible window of the flattened tree.
+      def render
+        window = visible_nodes[viewport_start, viewport_height] || []
+        window.each_with_index.map do |entry, index|
+          render_node(entry, viewport_start + index)
+        end.join("\n")
+      end
+
+      private
+
+      # Flattens the tree into visible rows: `{node:, depth:}` entries, skipping
+      # children of collapsed branches.
+      def visible_nodes
+        flatten(nodes, 0)
+      end
+
+      def flatten(list, depth)
+        Array(list).flat_map do |node|
+          entry = [{node: node, depth: depth}]
+          entry += flatten(node[:children], depth + 1) if branch?(node) && node[:expanded]
+          entry
+        end
+      end
+
+      # Renders one row: indentation, expansion marker, label; cursor row uses the
+      # selected style.
+      def render_node(entry, index)
+        node = entry.fetch(:node)
+        marker = if branch?(node)
+          node[:expanded] ? "▾ " : "▸ "
+        else
+          "  "
+        end
+        line = "#{"  " * entry.fetch(:depth)}#{marker}#{node[:label]}"
+        (index == cursor_index) ? theme.selected.render(line) : line
+      end
+
+      def branch?(node)
+        node && node[:children] && !node[:children].empty?
+      end
+
+      def select_or_toggle(node)
+        return [:selected, node] unless branch?(node)
+
+        toggle(node)
+        :handled
+      end
+
+      def toggle(node)
+        node[:expanded] = !node[:expanded]
+      end
+
+      def expand
+        node = current_node
+        node[:expanded] = true if branch?(node)
+      end
+
+      # Collapses an expanded branch, or moves the cursor to the parent of a leaf or
+      # collapsed node.
+      def collapse_or_parent
+        node = current_node
+        if branch?(node) && node[:expanded]
+          node[:expanded] = false
+        else
+          parent = parent_index(cursor_index)
+          @cursor_index = parent if parent
+        end
+      end
+
+      # Index of the nearest row above with a smaller depth (the parent), or nil.
+      def parent_index(index)
+        rows = visible_nodes
+        depth = rows[index]&.fetch(:depth)
+        return nil unless depth&.positive?
+
+        (index - 1).downto(0).find { |candidate| rows[candidate].fetch(:depth) < depth }
+      end
+
+      def move_up
+        @cursor_index -= 1 if cursor_index.positive?
+      end
+
+      def move_down
+        @cursor_index += 1 if cursor_index < visible_nodes.length - 1
+      end
+
+      def move_home
+        @cursor_index = 0
+      end
+
+      def move_end
+        @cursor_index = [visible_nodes.length - 1, 0].max
+      end
+
+      # Top row of the visible window, keeping the cursor in view.
+      def viewport_start
+        return 0 unless @height
+
+        Layout.selected_window_start(selected_index: cursor_index, item_count: visible_nodes.length, window_size: @height)
+      end
+
+      def viewport_height
+        @height || visible_nodes.length
+      end
+
+      def clamp_cursor
+        max = [visible_nodes.length - 1, 0].max
+        @cursor_index = cursor_index.clamp(0, max)
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/viewport/content_lines.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    class Viewport
+      # ContentLines normalizes viewport content into display lines.
+      class ContentLines
+        def initialize(content:, width:, wrap:)
+          @content = content
+          @window_width = width
+          @wrap = wrap
+        end
+
+        def lines
+          return wrapped_lines if wrap?
+
+          rendered_content.lines(chomp: true)
+        end
+
+        def display_width
+          lines.map { |line| UI::Width.measure(line) }.max || 0
+        end
+
+        private
+
+        attr_reader :content, :window_width, :wrap
+
+        def wrapped_lines
+          rendered_content.lines(chomp: true).flat_map { |line| wrap_line(line) }
+        end
+
+        def wrap_line(line)
+          line_width = UI::Width.measure(line)
+          return [""] if line_width.zero?
+
+          wrap_slices(line, line_width)
+        end
+
+        def wrap_slices(line, line_width)
+          (0...line_width).step(window_width).map do |start_column|
+            UI.visible_slice(line, start_column, window_width)
+          end
+        end
+
+        def rendered_content
+          content.respond_to?(:render) ? content.render.to_s : content.to_s
+        end
+
+        def wrap?
+          wrap && window_width&.positive?
+        end
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/viewport/line_window.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "unicode/display_width"
+
+module Charming
+  module Components
+    class Viewport
+      # LineWindow renders one content line inside the viewport's horizontal window.
+      class LineWindow
+        ANSI_PATTERN = /\e\[[0-9;]*m/
+
+        def initialize(width:, column:, wrap:)
+          @width = width
+          @column = column
+          @wrap = wrap
+        end
+
+        def render(line)
+          return line unless width
+          return pad_line(line, width) if wrap
+
+          pad_line(clip_line(line), width)
+        end
+
+        private
+
+        attr_reader :width, :column, :wrap
+
+        def clip_line(line)
+          clipped = clip_tokens(line.to_s)
+          needs_reset?(clipped) ? "#{clipped}\e[0m" : clipped
+        end
+
+        def clip_tokens(line)
+          state = {cursor: 0, output: +""}
+          line.scan(/#{ANSI_PATTERN}|./mo) do |token|
+            ansi?(token) ? append_ansi(state, token) : append_character(state, token)
+          end
+          state.fetch(:output)
+        end
+
+        def append_ansi(state, token)
+          state.fetch(:output) << token
+        end
+
+        def append_character(state, char)
+          char_width = Unicode::DisplayWidth.of(char)
+          cursor = state.fetch(:cursor)
+          state.fetch(:output) << char if visible?(cursor, char_width)
+          state[:cursor] = cursor + char_width
+        end
+
+        def visible?(cursor, char_width)
+          cursor >= column && cursor + char_width <= column + width
+        end
+
+        def needs_reset?(value)
+          value.match?(ANSI_PATTERN) && !value.end_with?("\e[0m")
+        end
+
+        def pad_line(line, target_width)
+          line + (" " * [target_width - UI::Width.measure(line), 0].max)
+        end
+
+        def ansi?(token)
+          token.match?(ANSI_PATTERN)
+        end
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/viewport/position.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    class Viewport
+      # Position owns the viewport's mutable row and column offsets.
+      class Position
+        attr_reader :offset, :column
+
+        def initialize(offset:, column:)
+          @offset = offset
+          @column = column
+        end
+
+        def scroll_up(bounds)
+          @offset -= 1
+          clamp(bounds)
+        end
+
+        def scroll_down(bounds)
+          @offset += 1
+          clamp(bounds)
+        end
+
+        def page_up(page_size, bounds)
+          @offset -= page_size
+          clamp(bounds)
+        end
+
+        def page_down(page_size, bounds)
+          @offset += page_size
+          clamp(bounds)
+        end
+
+        def home
+          @offset = 0
+          @column = 0
+        end
+
+        def end_at(bounds)
+          @offset = bounds.fetch(:max_offset)
+          @column = bounds.fetch(:max_column)
+        end
+
+        def scroll_left(bounds)
+          @column -= 1
+          clamp(bounds)
+        end
+
+        def scroll_right(bounds)
+          @column += 1
+          clamp(bounds)
+        end
+
+        def move_to(row, bounds)
+          @offset = row
+          clamp(bounds)
+        end
+
+        def clamp(bounds)
+          @offset = offset.clamp(0, bounds.fetch(:max_offset))
+          @column = column.clamp(0, bounds.fetch(:max_column))
+        end
+      end
+    end
+  end
+end