shoko 0.1.0

data/lib/shoko/adapters/output/terminal/terminal_service.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative '../../../core/services/base_service.rb'
+
+module Shoko
+  module Adapters::Output::Terminal
+      # Terminal interaction service for mouse and rendering coordination
+      class TerminalService < BaseService
+        # Maintain a global session depth so nested setup/cleanup calls
+        # (e.g., menu -> reader) don't flicker or drop to shell.
+        class << self
+          attr_accessor :session_depth
+        end
+        @session_depth = 0
+
+        def enable_mouse
+          Terminal.enable_mouse
+        end
+
+        def disable_mouse
+          Terminal.disable_mouse
+        end
+
+        def read_input_with_mouse(timeout: nil)
+          Terminal.read_input_with_mouse(timeout: timeout)
+        end
+
+        def read_key
+          Terminal.read_key
+        end
+
+        def size
+          Terminal.size
+        end
+
+        def end_frame
+          Terminal.end_frame
+        end
+
+        def setup
+          previous_depth = TerminalService.session_depth || 0
+          depth = previous_depth + 1
+          TerminalService.session_depth = depth
+          logger&.debug('terminal.setup', depth: depth)
+          return if previous_depth.positive?
+
+          Terminal.setup
+        rescue StandardError => e
+          TerminalService.session_depth = previous_depth
+          logger&.error('terminal.setup_failed', error: e.message)
+          raise
+        end
+
+        def cleanup(force: false)
+          return force_cleanup! if force
+
+          depth = decrement_session_depth
+          logger&.debug('terminal.cleanup', depth: depth)
+          return if depth.positive?
+
+          perform_terminal_cleanup
+        rescue StandardError => e
+          logger&.error('terminal.cleanup_failed', error: e.message)
+          raise
+        end
+
+        def force_cleanup
+          cleanup(force: true)
+        end
+
+        def start_frame(width: nil, height: nil)
+          Terminal.start_frame(width: width, height: height)
+        end
+
+        def read_key_blocking(timeout: nil)
+          Terminal.read_key_blocking(timeout: timeout)
+        end
+
+        # Read one blocking key, then drain a few non-blocking extras.
+        # Returns an array of keys, or [] if nothing was read.
+        #
+        # @param limit [Integer] maximum total keys to return
+        # @return [Array<String>]
+        def read_keys_blocking(limit: 10, timeout: nil)
+          first = read_key_blocking(timeout: timeout)
+          return [] unless first
+
+          keys = [first]
+          while (extra = read_key)
+            keys << extra
+            break if keys.size >= limit
+          end
+          keys
+        end
+
+        # Create a surface for component rendering
+        def create_surface
+          Shoko::Adapters::Output::Ui::Components::Surface.new(Terminal)
+        end
+
+        protected
+
+        def required_dependencies
+          [] # No dependencies required
+        end
+
+        private
+
+        def logger
+          @logger ||= begin
+            resolve(:logger)
+          rescue StandardError
+            nil
+          end
+        end
+
+        def force_cleanup!
+          depth = TerminalService.session_depth || 0
+          logger&.warn('terminal.cleanup.force', depth: depth)
+          TerminalService.session_depth = 0
+          perform_terminal_cleanup
+        end
+
+        def decrement_session_depth
+          depth = TerminalService.session_depth
+          return 0 unless depth
+
+          new_depth = depth.positive? ? depth - 1 : 0
+          TerminalService.session_depth = new_depth
+          new_depth
+        end
+
+        def perform_terminal_cleanup
+          Terminal.cleanup
+        end
+      end
+    end
+end

data/lib/shoko/adapters/output/terminal/text_metrics.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Output
+      module Terminal
+        # Utility helpers for measuring and truncating strings (with ANSI support)
+        # while respecting grapheme clusters and terminal cell widths.
+        module TextMetrics
+      begin
+        require 'reline'
+        require 'reline/unicode'
+        DISPLAY_WIDTH = ->(str) { Reline::Unicode.calculate_width(str) }
+      rescue LoadError, NameError
+        DISPLAY_WIDTH = lambda do |str|
+          str.to_s.scan(/\X/).sum { |cluster| cluster.length }
+        end
+      end
+      TAB_SIZE = 4
+      CSI_REGEX = %r{\e\[[0-?]*[ -/]*[@-~]}
+      ANSI_REGEX = CSI_REGEX
+      TOKEN_REGEX = /#{CSI_REGEX}|\X/m
+
+      module_function
+
+      def visible_length(text)
+        cell_data_for(strip_ansi(text.to_s)).sum { |cell| cell[:display_width] }
+      end
+
+      def cell_data_for(text)
+        expanded = expand_tabs(text.to_s)
+        cells = []
+        char_index = 0
+        screen_x = 0
+
+        expanded.each_grapheme_cluster do |cluster|
+          grapheme_length = cluster.length
+          display_width = display_width_for(cluster)
+
+          cells << {
+            cluster: cluster,
+            char_start: char_index,
+            char_end: char_index + grapheme_length,
+            display_width: display_width,
+            screen_x: screen_x,
+          }
+
+          char_index += grapheme_length
+          screen_x += display_width
+        end
+
+        cells
+      end
+
+      def strip_ansi(text)
+        text.to_s.gsub(ANSI_REGEX, '')
+      end
+
+      def display_width_for(cluster)
+        return TAB_SIZE if cluster == "\t"
+        return 0 if cluster == "\u00AD"
+
+        width = DISPLAY_WIDTH.call(cluster)
+        width = 1 if width <= 0 && !cluster.empty?
+        width
+      rescue StandardError
+        cluster.length
+      end
+
+      def expand_tabs(text, tab_size: TAB_SIZE)
+        column = 0
+        buffer = +''
+        text.to_s.each_grapheme_cluster do |cluster|
+          if cluster == "\t"
+            spaces = tab_size - (column % tab_size)
+            buffer << (' ' * spaces)
+            column += spaces
+          else
+            buffer << cluster
+            column += display_width_for(cluster)
+          end
+        end
+        buffer
+      end
+
+      def wrap_plain_text(line, width)
+        normalized = expand_tabs(line.to_s)
+        return [''] if normalized.empty?
+        return [normalized] if width.to_i <= 0
+
+        wrapped = []
+        current_line = +''
+        current_width = 0
+
+        width_i = width.to_i
+
+        normalized.split(/\s+/).each do |word|
+          next if word.nil? || word.empty?
+
+          word_width = visible_length(word)
+
+          if current_width.zero?
+            current_line.replace(word)
+            current_width = word_width
+          elsif current_width + 1 + word_width <= width_i
+            current_line << ' ' unless current_line.empty?
+            current_line << word
+            current_width += 1 + word_width
+          else
+            wrapped << current_line.dup unless current_line.empty?
+            current_line.replace(word)
+            current_width = word_width
+          end
+        end
+
+        wrapped << current_line.dup unless current_line.empty?
+        wrapped = [''] if wrapped.empty?
+        wrapped
+      end
+
+      def truncate_to(text, width, start_column: 0)
+        max_width = width.to_i
+        return '' if max_width <= 0
+
+        str = text.to_s
+        return '' if str.empty?
+
+        # Fast-path: preserve original when it already fits and contains no tab/newline.
+        if !(str.include?("\t") || str.include?("\n") || str.include?("\r")) && (max_width >= visible_length(str))
+          return str
+        end
+
+        buffer = +''
+        current_width = 0
+        column = start_column.to_i
+
+        str.scan(TOKEN_REGEX).each do |token|
+          if token.start_with?("\e[")
+            buffer << token
+            next
+          end
+
+          next if token == "\e"
+
+          remaining = max_width - current_width
+          break if remaining <= 0
+
+          case token
+          when "\t"
+            spaces = TAB_SIZE - (column % TAB_SIZE)
+            take = [spaces, remaining].min
+            buffer << (' ' * take)
+            current_width += take
+            column += take
+          when "\n", "\r"
+            # Never allow newlines to affect terminal layout; treat as a space.
+            break if remaining < 1
+
+            buffer << ' '
+            current_width += 1
+            column += 1
+          else
+            token_width = display_width_for(token)
+            break if token_width > remaining
+
+            buffer << token
+            current_width += token_width
+            column += token_width
+          end
+        end
+
+        buffer
+      end
+
+      def pad_right(text, width, start_column: 0, pad: ' ')
+        w = width.to_i
+        return '' if w <= 0
+
+        clipped = truncate_to(text.to_s, w, start_column: start_column)
+        pad_len = w - visible_length(clipped)
+        pad_len.positive? ? (clipped + (pad.to_s * pad_len)) : clipped
+      end
+
+      def pad_left(text, width, start_column: 0, pad: ' ')
+        w = width.to_i
+        return '' if w <= 0
+
+        clipped = truncate_to(text.to_s, w, start_column: start_column)
+        pad_len = w - visible_length(clipped)
+        pad_len.positive? ? ((pad.to_s * pad_len) + clipped) : clipped
+      end
+
+      def pad_center(text, width, start_column: 0, pad: ' ')
+        w = width.to_i
+        return '' if w <= 0
+
+        clipped = truncate_to(text.to_s, w, start_column: start_column)
+        pad_len = w - visible_length(clipped)
+        return clipped unless pad_len.positive?
+
+        left = pad_len / 2
+        right = pad_len - left
+        (pad.to_s * left) + clipped + (pad.to_s * right)
+      end
+
+      # Wraps text by terminal cell width without splitting grapheme clusters.
+      # Preserves newlines and expands tabs relative to the provided start column.
+      #
+      # This is intended for UI text entry/display helpers (notes, dialogs),
+      # not for paragraph-aware ebook formatting.
+      def wrap_cells(text, width, start_column: 0)
+        w = width.to_i
+        return [''] if w <= 0
+
+        lines = []
+        line = +''
+        line_width = 0
+        column = start_column.to_i
+
+        text.to_s.each_grapheme_cluster do |cluster|
+          if cluster == "\n"
+            lines << line.dup
+            line.clear
+            line_width = 0
+            column = start_column.to_i
+            next
+          end
+
+          cluster = ' ' if cluster == "\r"
+
+          if cluster == "\t"
+            spaces = TAB_SIZE - (column % TAB_SIZE)
+            spaces.times do
+              if line_width >= w
+                lines << line.dup
+                line.clear
+                line_width = 0
+                column = start_column.to_i
+              end
+              line << ' '
+              line_width += 1
+              column += 1
+            end
+            next
+          end
+
+          cw = display_width_for(cluster)
+          next if cw <= 0
+          next if cw > w
+
+          if line_width.positive? && (line_width + cw > w)
+            lines << line.dup
+            line.clear
+            line_width = 0
+            column = start_column.to_i
+          end
+
+          break if cw > (w - line_width)
+
+          line << cluster
+          line_width += cw
+          column += cw
+        end
+
+        lines << line.dup
+        lines = [''] if lines.empty?
+        lines
+      end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/output/ui/builders/page_setup_builder.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Output::Ui::Builders
+    # Builder for page setup configuration
+    class PageSetupBuilder
+      attr_reader :setup
+
+      def initialize
+        @setup = PageSetup.new
+      end
+
+      def with_lines(lines)
+        @setup.lines = lines
+        self
+      end
+
+      def with_wrapped(wrapped)
+        @setup.wrapped = wrapped
+        self
+      end
+
+      def with_dimensions(col_width, content_height, displayable_lines)
+        @setup.col_width = col_width
+        @setup.content_height = content_height
+        @setup.displayable_lines = displayable_lines
+        self
+      end
+
+      def with_position(col_start)
+        @setup.col_start = col_start
+        self
+      end
+
+      def build
+        @setup
+      end
+    end
+
+    # Data structure representing page setup parameters
+    PageSetup = Struct.new(
+      :lines, :wrapped, :col_width, :col_start,
+      :content_height, :displayable_lines,
+      keyword_init: true
+    )
+  end
+end

data/lib/shoko/adapters/output/ui/components/annotation_editor_overlay/footer_renderer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative '../../../terminal/terminal.rb'
+require_relative '../../../terminal/text_metrics.rb'
+
+module Shoko
+  module Adapters::Output::Ui::Components
+    # Namespace for annotation editor overlay helpers.
+    module AnnotationEditorOverlay
+      # Renders the footer buttons for the annotation editor overlay.
+      class FooterRenderer
+        SegmentSpec = Struct.new(:row, :col, :key, :text, :width, keyword_init: true)
+
+        def initialize(background:, text_fg:, key_fg:)
+          @background = background
+          @text_fg = text_fg
+          @key_fg = key_fg
+        end
+
+        def render(surface, bounds, geometry)
+          button_row = geometry.buttons_row
+          fill_footer(surface, bounds, geometry, button_row)
+          save_spec, cancel_spec = segment_specs(geometry, button_row)
+
+          draw_segment(surface, bounds, save_spec)
+          draw_segment(surface, bounds, cancel_spec)
+
+          abs_row = geometry.button_row_abs(bounds)
+          {
+            save: region_for(bounds, abs_row, save_spec),
+            cancel: region_for(bounds, abs_row, cancel_spec),
+          }
+        end
+
+        private
+
+        def fill_footer(surface, bounds, geometry, button_row)
+          footer_bg = "#{@background}#{' ' * geometry.content_width}#{Terminal::ANSI::RESET}"
+          surface.write(bounds, button_row, geometry.content_x, footer_bg)
+        end
+
+        def segment_specs(geometry, button_row)
+          save_spec = build_segment_spec(geometry, button_row, key: 'Ctrl+S', text: 'Save', align: :left)
+          cancel_spec = build_segment_spec(geometry, button_row, key: 'Esc', text: 'Cancel', align: :right)
+
+          min_cancel_col = save_spec.col + save_spec.width + 2
+          max_cancel_col = geometry.content_x + geometry.content_width - cancel_spec.width
+          cancel_spec.col = [min_cancel_col, max_cancel_col].min if cancel_spec.col < min_cancel_col
+
+          [save_spec, cancel_spec]
+        end
+
+        def build_segment_spec(geometry, row, key:, text:, align:)
+          label = "#{key} #{text}"
+          width = Shoko::Adapters::Output::Terminal::TextMetrics.visible_length(label)
+
+          col = if align == :right
+                  geometry.content_x + geometry.content_width - width
+                else
+                  geometry.content_x
+                end
+          col = [col, geometry.content_x].max
+
+          SegmentSpec.new(row: row, col: col, key: key, text: text, width: width)
+        end
+
+        def draw_segment(surface, bounds, spec)
+          reset = Terminal::ANSI::RESET
+          label = "#{@background}#{@key_fg}#{spec.key}#{reset}" \
+                  "#{@background}#{@text_fg} #{spec.text}#{reset}"
+          surface.write(bounds, spec.row, spec.col, label)
+        end
+
+        def region_for(bounds, abs_row, spec)
+          { row: abs_row, col: bounds.x + spec.col - 1, width: spec.width }
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/output/ui/components/annotation_editor_overlay/geometry.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Output::Ui::Components
+    # Namespace for annotation editor overlay helpers.
+    module AnnotationEditorOverlay
+      # Geometry helper for the annotation editor overlay content region.
+      class Geometry
+        attr_reader :layout
+
+        def initialize(layout)
+          @layout = layout
+        end
+
+        def content_x
+          layout.inner_x + 2
+        end
+
+        def content_width
+          [layout.inner_width - 4, 1].max
+        end
+
+        def header_row
+          layout.inner_y + 1
+        end
+
+        def subheader_row
+          header_row + 1
+        end
+
+        def label_row
+          subheader_row + 2
+        end
+
+        def note_top
+          label_row + 1
+        end
+
+        def note_rows
+          [buttons_row - note_top, 1].max
+        end
+
+        def text_x
+          content_x
+        end
+
+        def text_width
+          content_width
+        end
+
+        def buttons_row
+          layout.inner_y + layout.inner_height - 2
+        end
+
+        def button_row_abs(bounds)
+          bounds.y + buttons_row - 1
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/output/ui/components/annotation_editor_overlay/note_renderer.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative '../ui/text_utils'
+require_relative '../../../terminal/text_metrics.rb'
+require_relative '../../../terminal/terminal.rb'
+
+module Shoko
+  module Adapters::Output::Ui::Components
+    # Namespace for annotation editor overlay helpers.
+    module AnnotationEditorOverlay
+      # Renders note contents and cursor inside the annotation editor overlay.
+      class NoteRenderer
+        def initialize(background:, text_color:, cursor_color:, geometry:, placeholder_text: nil,
+                       placeholder_color: nil)
+          @background = background
+          @text_color = text_color
+          @cursor_color = cursor_color
+          @geometry = geometry
+          @placeholder_text = placeholder_text
+          @placeholder_color = placeholder_color
+        end
+
+        def render(surface, bounds, note:, cursor_pos:)
+          note_text = note.to_s
+          wrapped_note = wrap_lines(note_text, @geometry.text_width)
+          cursor_lines = wrap_lines(note_text[0...cursor_pos], @geometry.text_width)
+          cursor_line_index = [cursor_lines.length - 1, 0].max
+
+          visible_start, visible_lines = visible_window(wrapped_note, cursor_line_index, @geometry.note_rows)
+          render_lines(surface, bounds, visible_lines)
+          render_placeholder(surface, bounds) if note_text.strip.empty?
+          cursor_row, cursor_col = cursor_position(cursor_lines, cursor_line_index, visible_start)
+          render_cursor(surface, bounds, cursor_row, cursor_col)
+        end
+
+        private
+
+        def wrap_lines(text, width)
+          lines = UI::TextUtils.wrap_text(text.to_s, width)
+          lines.empty? ? [''] : lines
+        end
+
+        def visible_window(lines, cursor_line_index, note_rows)
+          max_start = [lines.length - note_rows, 0].max
+          visible_start = [cursor_line_index - note_rows + 1, 0].max
+          visible_start = [visible_start, max_start].min
+          visible_lines = lines[visible_start, note_rows] || []
+          visible_lines += Array.new(note_rows - visible_lines.length, '')
+          [visible_start, visible_lines]
+        end
+
+        def render_lines(surface, bounds, lines)
+          lines.each_with_index do |line, idx|
+            row = @geometry.note_top + idx
+            padded = UI::TextUtils.pad_right(line, @geometry.text_width)
+            surface.write(bounds, row, @geometry.text_x,
+                          "#{@background}#{@text_color}#{padded}#{Terminal::ANSI::RESET}")
+          end
+        end
+
+        def render_placeholder(surface, bounds)
+          return unless @placeholder_text && @placeholder_color
+
+          truncated = Shoko::Adapters::Output::Terminal::TextMetrics.truncate_to(@placeholder_text, @geometry.text_width)
+          padded = UI::TextUtils.pad_right(truncated, @geometry.text_width)
+          surface.write(bounds, @geometry.note_top, @geometry.text_x,
+                        "#{@background}#{@placeholder_color}#{padded}#{Terminal::ANSI::RESET}")
+        end
+
+        def cursor_position(cursor_lines, cursor_line_index, visible_start)
+          cursor_display_row = (cursor_line_index - visible_start).clamp(0, @geometry.note_rows - 1)
+          cursor_row = @geometry.note_top + cursor_display_row
+          cursor_line = cursor_lines.last || ''
+          cursor_col = @geometry.text_x + [Shoko::Adapters::Output::Terminal::TextMetrics.visible_length(cursor_line),
+                                           @geometry.text_width - 1].min
+          [cursor_row, cursor_col]
+        end
+
+        def render_cursor(surface, bounds, cursor_row, cursor_col)
+          surface.write(bounds, cursor_row, cursor_col,
+                        "#{@background}#{@cursor_color}_#{Terminal::ANSI::RESET}")
+        end
+      end
+    end
+  end
+end