rubytui 1.2.3

data/lib/rubytui/widgets/block.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Built-in widgets.
+  #
+  # Stateless widgets include {Widget} and implement <tt>render(area, buf)</tt>.
+  # Stateful widgets include {StatefulWidget} and implement
+  # <tt>render(area, buf, state)</tt> with an application-owned state object
+  # such as {ListState}, {TableState} or {InputState}.
+  module Widgets
+    # Block is the most fundamental widget: a rectangular area with optional
+    # borders, title, and padding. Other widgets are typically rendered inside
+    # a Block's inner area.
+    #
+    # @example Bordered block with a centered title
+    #   block = RubyTUI::Widgets::Block.new(title: " Status ", title_alignment: :center)
+    #   frame.render_widget(block, area)
+    #   content_area = block.inner(area)
+    class Block
+      include Widget
+
+      # Border configuration
+
+      # No borders.
+      NONE   = :none
+      # All four borders.
+      ALL    = :all
+      # Top border.
+      TOP    = :top
+      # Bottom border.
+      BOTTOM = :bottom
+      # Left border.
+      LEFT   = :left
+      # Right border.
+      RIGHT  = :right
+
+      attr_reader :title, :title_alignment, :borders, :border_set,
+                  :border_style, :style, :padding
+
+      # @param title [String, nil] title drawn on the top border, truncated to fit
+      #   between the corners; not drawn when the top border is disabled
+      # @param title_alignment [Symbol] +:left+ (default, one cell in from the
+      #   left corner), +:center+, or +:right+
+      # @param title_style [Style, nil] title style (default: nil, uses +border_style+)
+      # @param borders [Symbol, Array<Symbol>, Boolean, nil] sides to draw:
+      #   +:all+ or +true+ (default: {ALL}), +:none+, +false+ or +nil+ for none,
+      #   a single side symbol (+:top+, +:bottom+, +:left+, +:right+), or an
+      #   Array of side symbols (the Array is frozen in place); any other value
+      #   draws all sides
+      # @param border_set [Symbols::BorderSet] border characters (default: {Symbols::ROUNDED})
+      # @param border_style [Style] style of the border characters (default: {Style::DEFAULT})
+      # @param style [Style] style patched onto every cell of the area when it is
+      #   not {Style::DEFAULT} (default: {Style::DEFAULT})
+      # @param padding [Integer, Array<Integer>, nil] space inside the borders:
+      #   an Integer for all sides, or an Array of 1 (all sides), 2
+      #   (<tt>[vertical, horizontal]</tt>) or 4 (<tt>[top, right, bottom, left]</tt>)
+      #   values; +nil+ or any other shape means no padding (default: nil)
+      def initialize(
+        title: nil,
+        title_alignment: :left,
+        title_style: nil,
+        borders: ALL,
+        border_set: Symbols::ROUNDED,
+        border_style: Style::DEFAULT,
+        style: Style::DEFAULT,
+        padding: nil  # [top, right, bottom, left] or single integer
+      )
+        @title = title
+        @title_alignment = title_alignment
+        @title_style = title_style || border_style
+        @borders = normalize_borders(borders)
+        @border_set = border_set
+        @border_style = border_style
+        @style = style
+        @padding = normalize_padding(padding)
+      end
+
+      # Calculate the inner area (area minus borders and padding)
+      #
+      # @param area [Rect] the outer area of the block
+      # @return [Rect] the area inside the enabled borders and padding (width and
+      #   height clamped to >= 0), or {Rect::ZERO} if +area+ is empty
+      def inner(area)
+        return Rect::ZERO if area.empty?
+
+        x = area.x
+        y = area.y
+        w = area.width
+        h = area.height
+
+        if @borders.include?(:left)
+          x += 1
+          w -= 1
+        end
+        if @borders.include?(:right)
+          w -= 1
+        end
+        if @borders.include?(:top)
+          y += 1
+          h -= 1
+        end
+        if @borders.include?(:bottom)
+          h -= 1
+        end
+
+        # Apply padding
+        x += @padding[3]  # left
+        y += @padding[0]  # top
+        w -= @padding[1] + @padding[3]  # right + left
+        h -= @padding[0] + @padding[2]  # top + bottom
+
+        Rect.new(x: x, y: y, width: [w, 0].max, height: [h, 0].max)
+      end
+
+      # Render the block's background, borders and title.
+      #
+      # The background +style+ is patched onto every cell of +area+ unless it is
+      # {Style::DEFAULT}. Child content is not rendered; draw it into {#inner}.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @return [void]
+      def render(area, buf)
+        return if area.empty?
+
+        # Fill background
+        buf.set_style(area, @style) if @style != Style::DEFAULT
+
+        # Draw borders
+        render_borders(area, buf)
+
+        # Draw title
+        render_title(area, buf) if @title
+      end
+
+      private
+
+      def render_borders(area, buf)
+        has_top    = @borders.include?(:top)
+        has_bottom = @borders.include?(:bottom)
+        has_left   = @borders.include?(:left)
+        has_right  = @borders.include?(:right)
+
+        # Top border
+        if has_top
+          # Top-left corner
+          if has_left
+            buf[area.x, area.y]&.set(@border_set.top_left, @border_style)
+          end
+          # Top horizontal line
+          x_start = area.x + (has_left ? 1 : 0)
+          x_end = area.right - (has_right ? 1 : 0)
+          (x_start...x_end).each do |x|
+            buf[x, area.y]&.set(@border_set.horizontal, @border_style)
+          end
+          # Top-right corner
+          if has_right
+            buf[area.right - 1, area.y]&.set(@border_set.top_right, @border_style)
+          end
+        end
+
+        # Bottom border
+        if has_bottom
+          bottom_y = area.bottom - 1
+          if has_left
+            buf[area.x, bottom_y]&.set(@border_set.bottom_left, @border_style)
+          end
+          x_start = area.x + (has_left ? 1 : 0)
+          x_end = area.right - (has_right ? 1 : 0)
+          (x_start...x_end).each do |x|
+            buf[x, bottom_y]&.set(@border_set.horizontal, @border_style)
+          end
+          if has_right
+            buf[area.right - 1, bottom_y]&.set(@border_set.bottom_right, @border_style)
+          end
+        end
+
+        # Left border (vertical)
+        if has_left
+          y_start = area.y + (has_top ? 1 : 0)
+          y_end = area.bottom - (has_bottom ? 1 : 0)
+          (y_start...y_end).each do |y|
+            buf[area.x, y]&.set(@border_set.vertical, @border_style)
+          end
+        end
+
+        # Right border (vertical)
+        if has_right
+          y_start = area.y + (has_top ? 1 : 0)
+          y_end = area.bottom - (has_bottom ? 1 : 0)
+          (y_start...y_end).each do |y|
+            buf[area.right - 1, y]&.set(@border_set.vertical, @border_style)
+          end
+        end
+      end
+
+      def render_title(area, buf)
+        return unless @borders.include?(:top)
+
+        has_left = @borders.include?(:left)
+        has_right = @borders.include?(:right)
+
+        # Available width for title (between corners)
+        x_start = area.x + (has_left ? 1 : 0)
+        x_end = area.right - (has_right ? 1 : 0)
+        available = x_end - x_start
+
+        return if available <= 0
+
+        title_text = Buffer.truncate_to_width(@title, available)
+        title_width = Buffer.string_width(title_text)
+
+        x = case @title_alignment
+            when :center
+              x_start + (available - title_width) / 2
+            when :right
+              x_end - title_width
+            else # :left
+              x_start + 1  # 1 cell padding from left border
+            end
+
+        x = [x, x_start].max
+        buf.set_string(x, area.y, title_text, @title_style)
+      end
+
+      def normalize_borders(borders)
+        case borders
+        when :all, true
+          [:top, :bottom, :left, :right].freeze
+        when :none, false, nil
+          [].freeze
+        when Symbol
+          [borders].freeze
+        when Array
+          borders.freeze
+        else
+          [:top, :bottom, :left, :right].freeze
+        end
+      end
+
+      def normalize_padding(padding)
+        case padding
+        when nil
+          [0, 0, 0, 0]
+        when Integer
+          [padding, padding, padding, padding]
+        when Array
+          case padding.length
+          when 1 then [padding[0]] * 4
+          when 2 then [padding[0], padding[1], padding[0], padding[1]]
+          when 4 then padding
+          else [0, 0, 0, 0]
+          end
+        else
+          [0, 0, 0, 0]
+        end
+      end
+    end
+  end
+end

data/lib/rubytui/widgets/canvas.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Widgets
+    # Canvas provides sub-cell resolution drawing using Braille Unicode characters.
+    # Each terminal cell maps to a 2x4 grid of dots (U+2800 to U+28FF).
+    # This gives 2x horizontal and 4x vertical resolution compared to regular cells.
+    #
+    # Shapes are added in data coordinates and mapped onto the dot grid; coordinates
+    # outside the bounds are clamped to the nearest edge.
+    #
+    # @example
+    #   canvas = RubyTUI::Widgets::Canvas.new(x_bounds: [0, 10], y_bounds: [0, 10])
+    #   canvas.line(0, 0, 10, 10).point(5, 2).label(1, 9, "peak")
+    #   frame.render_widget(canvas, area)
+    class Canvas
+      include Widget
+
+      # Braille dot positions within a cell:
+      #   0  3
+      #   1  4
+      #   2  5
+      #   6  7
+      # Bit positions map to these dot positions.
+      DOT_PATTERNS = [
+        0x01, 0x02, 0x04, 0x08,
+        0x10, 0x20, 0x40, 0x80
+      ].freeze
+
+      # Code point of the empty Braille pattern (U+2800); dot bits are added to it.
+      BRAILLE_BASE = 0x2800
+
+      attr_reader :width, :height
+
+      # @param x_bounds [Array(Numeric, Numeric), nil] <tt>[min, max]</tt> data range
+      #   mapped to the canvas width (default: nil, computed from the x coordinates
+      #   of points and lines)
+      # @param y_bounds [Array(Numeric, Numeric), nil] <tt>[min, max]</tt> data range
+      #   mapped to the canvas height, max at the top (default: nil; the automatic
+      #   range is currently also computed from the x coordinates of points and lines)
+      # @param style [Style] style for labels added without a style (default: {Style::DEFAULT})
+      # @param marker_style [Style, nil] style for dots drawn without a style
+      #   (default: white foreground)
+      # @param block [Widgets::Block, nil] optional wrapping block
+      def initialize(
+        x_bounds: nil,
+        y_bounds: nil,
+        style: Style::DEFAULT,
+        marker_style: nil,
+        block: nil
+      )
+        @x_bounds = x_bounds  # [min, max] for x coordinate mapping
+        @y_bounds = y_bounds  # [min, max] for y coordinate mapping
+        @style = style
+        @marker_style = marker_style || Style.new.fg(Color::WHITE)
+        @block = block
+        @points = []
+        @lines = []
+        @labels = []
+      end
+
+      # Add a point at (x, y) in data coordinates
+      #
+      # @param x [Numeric] x data coordinate
+      # @param y [Numeric] y data coordinate
+      # @param style [Style, nil] dot style (default: nil, uses +marker_style+)
+      # @return [self]
+      def point(x, y, style: nil)
+        @points << [x, y, style]
+        self
+      end
+
+      # Add multiple points
+      #
+      # @param coords [Array<Array(Numeric, Numeric)>] <tt>[x, y]</tt> pairs in data coordinates
+      # @param style [Style, nil] dot style for all points (default: nil, uses +marker_style+)
+      # @return [self]
+      def points(coords, style: nil)
+        coords.each { |x, y| @points << [x, y, style] }
+        self
+      end
+
+      # Add a line from (x1, y1) to (x2, y2)
+      #
+      # @param x1 [Numeric] start x data coordinate
+      # @param y1 [Numeric] start y data coordinate
+      # @param x2 [Numeric] end x data coordinate
+      # @param y2 [Numeric] end y data coordinate
+      # @param style [Style, nil] dot style for the line (default: nil, uses +marker_style+)
+      # @return [self]
+      def line(x1, y1, x2, y2, style: nil)
+        @lines << [x1, y1, x2, y2, style]
+        self
+      end
+
+      # Add a text label at (x, y) in data coordinates
+      #
+      # @param x [Numeric] x data coordinate
+      # @param y [Numeric] y data coordinate
+      # @param text [String] text drawn starting at the cell that contains (x, y)
+      # @param style [Style, nil] text style (default: nil, uses the canvas +style+)
+      # @return [self]
+      def label(x, y, text, style: nil)
+        @labels << [x, y, text, style]
+        self
+      end
+
+      # Rasterize all added lines, points and labels into the buffer.
+      #
+      # Lines are drawn first, then points, as Braille dots. Each cell takes the
+      # style of the last styled dot drawn in it, otherwise +marker_style+. Labels
+      # are drawn last, on top of the dots. Added shapes are kept between renders.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @return [void]
+      def render(area, buf)
+        return if area.empty?
+
+        render_area = area
+        if @block
+          @block.render(area, buf)
+          render_area = @block.inner(area)
+        end
+
+        return if render_area.empty?
+
+        # Canvas resolution: each cell is 2 dots wide, 4 dots tall
+        canvas_w = render_area.width * 2
+        canvas_h = render_area.height * 4
+
+        # Initialize dot grid (indexed by canvas pixel coordinates)
+        grid = Array.new(render_area.height) { Array.new(render_area.width, 0) }
+        style_grid = Array.new(render_area.height) { Array.new(render_area.width, nil) }
+
+        # Compute bounds
+        x_min, x_max = compute_bounds(@x_bounds, canvas_w)
+        y_min, y_max = compute_bounds(@y_bounds, canvas_h)
+
+        # Rasterize lines
+        @lines.each do |x1, y1, x2, y2, lstyle|
+          rasterize_line(x1, y1, x2, y2, lstyle, grid, style_grid,
+                         x_min, x_max, y_min, y_max, canvas_w, canvas_h)
+        end
+
+        # Rasterize points
+        @points.each do |px, py, pstyle|
+          cx, cy = data_to_canvas(px, py, x_min, x_max, y_min, y_max, canvas_w, canvas_h)
+          set_dot(grid, style_grid, cx, cy, pstyle, render_area.width, render_area.height)
+        end
+
+        # Render grid to buffer
+        render_area.height.times do |row|
+          render_area.width.times do |col|
+            pattern = grid[row][col]
+            next if pattern == 0
+
+            char = (BRAILLE_BASE + pattern).chr("UTF-8")
+            cell_style = style_grid[row][col] || @marker_style
+            buf[render_area.x + col, render_area.y + row]&.set(char, cell_style)
+          end
+        end
+
+        # Render labels
+        @labels.each do |lx, ly, text, lstyle|
+          cx, cy = data_to_canvas(lx, ly, x_min, x_max, y_min, y_max, canvas_w, canvas_h)
+          cell_x = render_area.x + cx / 2
+          cell_y = render_area.y + cy / 4
+          buf.set_string(cell_x, cell_y, text, lstyle || @style)
+        end
+      end
+
+      private
+
+      def compute_bounds(bounds, canvas_size)
+        if bounds
+          [bounds[0].to_f, bounds[1].to_f]
+        else
+          all_x = @points.map { |p| p[0] } + @lines.flat_map { |l| [l[0], l[2]] }
+          return [0.0, canvas_size.to_f] if all_x.empty?
+
+          mn = all_x.min.to_f
+          mx = all_x.max.to_f
+          mx = mn + 1 if mx == mn
+          [mn, mx]
+        end
+      end
+
+      def data_to_canvas(dx, dy, x_min, x_max, y_min, y_max, cw, ch)
+        cx = ((dx - x_min) / (x_max - x_min) * (cw - 1)).round.clamp(0, cw - 1)
+        # Y is inverted: data y=max is canvas y=0 (top)
+        cy = ((y_max - dy) / (y_max - y_min) * (ch - 1)).round.clamp(0, ch - 1)
+        [cx, cy]
+      end
+
+      def set_dot(grid, style_grid, cx, cy, dot_style, grid_w, grid_h)
+        cell_col = cx / 2
+        cell_row = cy / 4
+        return if cell_col >= grid_w || cell_row >= grid_h
+
+        # Determine which dot within the cell
+        dot_x = cx % 2  # 0 or 1
+        dot_y = cy % 4  # 0, 1, 2, or 3
+
+        # Map to braille bit position
+        bit_index = if dot_y < 3
+                      dot_y + (dot_x * 3)  # positions 0-2 (left) or 3-5 (right)
+                    else
+                      6 + dot_x  # positions 6 (left) or 7 (right)
+                    end
+
+        grid[cell_row][cell_col] |= DOT_PATTERNS[bit_index]
+        style_grid[cell_row][cell_col] = dot_style if dot_style
+      end
+
+      # Bresenham's line algorithm in canvas (dot) coordinates
+      def rasterize_line(x1, y1, x2, y2, lstyle, grid, style_grid,
+                         x_min, x_max, y_min, y_max, cw, ch)
+        cx1, cy1 = data_to_canvas(x1, y1, x_min, x_max, y_min, y_max, cw, ch)
+        cx2, cy2 = data_to_canvas(x2, y2, x_min, x_max, y_min, y_max, cw, ch)
+
+        dx = (cx2 - cx1).abs
+        dy = -(cy2 - cy1).abs
+        sx = cx1 < cx2 ? 1 : -1
+        sy = cy1 < cy2 ? 1 : -1
+        err = dx + dy
+
+        gw = grid[0]&.length || 0
+        gh = grid.length
+
+        loop do
+          set_dot(grid, style_grid, cx1, cy1, lstyle, gw, gh)
+          break if cx1 == cx2 && cy1 == cy2
+
+          e2 = 2 * err
+          if e2 >= dy
+            err += dy
+            cx1 += sx
+          end
+          if e2 <= dx
+            err += dx
+            cy1 += sy
+          end
+        end
+      end
+    end
+  end
+end