ratatui_ruby 0.4.0 → 0.6.0

data/lib/ratatui_ruby/schema/tabs.rb

@@ -4,81 +4,80 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Displays a tab bar for navigation.
-    #
-    # Screen real estate is limited. You cannot show everything at once. Segregating content into views is necessary for complex apps.
-    #
-    # This widget separates dimensions. It displays a row of titles, indicating which view is active.
-    #
-    # Use it at the top of your interface to switch between major modes or contexts.
-    #
-    # === Examples
-    #
-    #   Tabs.new(
-    #     titles: ["Home", "Settings", "Logs"],
-    #     selected_index: 0,
-    #     highlight_style: Style.new(fg: :yellow),
-    #     divider: "|"
-    #   )
-    class Tabs < Data.define(:titles, :selected_index, :block, :divider, :highlight_style, :style, :padding_left, :padding_right)
-      ##
-      # :attr_reader: titles
-      # Tab titles (Array of Strings).
+  # Displays a tab bar for navigation.
+  #
+  # Screen real estate is limited. You cannot show everything at once. Segregating content into views is necessary for complex apps.
+  #
+  # This widget separates dimensions. It displays a row of titles, indicating which view is active.
+  #
+  # Use it at the top of your interface to switch between major modes or contexts.
+  #
+  # {rdoc-image:/doc/images/widget_tabs_demo.png}[link:/examples/widget_tabs_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_tabs_demo/app.rb
+  class Tabs < Data.define(:titles, :selected_index, :block, :divider, :highlight_style, :style, :padding_left, :padding_right)
+    ##
+    # :attr_reader: titles
+    # Tab titles (Array of Strings).
 
-      ##
-      # :attr_reader: selected_index
-      # Index of the active tab.
+    ##
+    # :attr_reader: selected_index
+    # Index of the active tab.
 
-      ##
-      # :attr_reader: block
-      # Optional wrapping block.
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
 
-      ##
-      # :attr_reader: divider
-      # Separator string between tabs.
+    ##
+    # :attr_reader: divider
+    # Separator string between tabs.
 
-      ##
-      # :attr_reader: highlight_style
-      # Style for the selected tab title.
+    ##
+    # :attr_reader: highlight_style
+    # Style for the selected tab title.
 
-      ##
-      # :attr_reader: style
-      # Base style for the tabs area.
+    ##
+    # :attr_reader: style
+    # Base style for the tabs area.
 
-      ##
-      # :attr_reader: padding_left
-      # Left padding for the tabs area (Integer, default: 0).
+    ##
+    # :attr_reader: padding_left
+    # Left padding for the tabs area (Integer, default: 0).
 
-      ##
-      # :attr_reader: padding_right
-      # Right padding for the tabs area (Integer, default: 0).
+    ##
+    # :attr_reader: padding_right
+    # Right padding for the tabs area (Integer, default: 0).
 
-      # Creates a new Tabs widget.
-      #
-      # [titles] Array of Strings/Lines.
-      # [selected_index] Integer (default: 0).
-      # [block] Block (optional).
-      # [divider] String (optional).
-      # [highlight_style] Style (optional).
-      # [style] Style (optional).
-      # [padding_left] Integer (default: 0).
-      # [padding_right] Integer (default: 0).
-      def initialize(titles: [], selected_index: 0, block: nil, divider: nil, highlight_style: nil, style: nil, padding_left: 0, padding_right: 0)
-        super(
-          titles: titles,
-          selected_index: Integer(selected_index),
-          block: block,
-          divider: divider,
-          highlight_style: highlight_style,
-          style: style,
-          padding_left: Integer(padding_left),
-          padding_right: Integer(padding_right)
-        )
-      end
+    # Creates a new Tabs widget.
+    #
+    # [titles] Array of Strings/Lines.
+    # [selected_index] Integer (default: 0).
+    # [block] Block (optional).
+    # [divider] String (optional).
+    # [highlight_style] Style (optional).
+    # [style] Style (optional).
+    # [padding_left] Integer (default: 0).
+    # [padding_right] Integer (default: 0).
+    def initialize(titles: [], selected_index: 0, block: nil, divider: nil, highlight_style: nil, style: nil, padding_left: 0, padding_right: 0)
+      super(
+        titles:,
+        selected_index: Integer(selected_index),
+        block:,
+        divider:,
+        highlight_style:,
+        style:,
+        padding_left: Integer(padding_left),
+        padding_right: Integer(padding_right)
+      )
+    end
 
-      # Returns the total width of the tabs.
-      def width
-        RatatuiRuby._tabs_width(self)
-      end
+    # Returns the total width of the tabs.
+    def width
+      RatatuiRuby._tabs_width(self)
     end
+  end
 end

data/lib/ratatui_ruby/schema/text.rb

@@ -4,8 +4,42 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # Namespace for rich text components (Span and Line).
+  # Namespace for rich text components (Span, Line) and text utilities.
   # Distinct from canvas shapes and other Line usages.
+  #
+  # == Text Measurement
+  #
+  # The Text module provides a utility method for calculating the display width
+  # of strings in terminal cells. This accounts for unicode complexity:
+  #
+  # - ASCII characters: 1 cell each
+  # - CJK (Chinese, Japanese, Korean) characters: 2 cells each (full-width)
+  # - Emoji: typically 2 cells each (varies by terminal)
+  # - Combining marks: 0 cells (zero-width)
+  #
+  # This is essential for layout calculations in TUI applications, where you need to know
+  # how much space a string will occupy on the screen, not just its byte or character length.
+  #
+  # === Use Cases
+  #
+  # - Auto-sizing widgets (Button, Badge) that fit their content
+  # - Calculating padding or centering for text alignment
+  # - Building responsive layouts that adapt to content width
+  # - Measuring text for scrolling or truncation logic
+  #
+  # === Examples
+  #
+  #   # Simple ASCII text
+  #   RatatuiRuby::Text.width("Hello")        # => 5
+  #
+  #   # With emoji
+  #   RatatuiRuby::Text.width("Hello 👍")     # => 8 (5 + space + 2-width emoji)
+  #
+  #   # With CJK characters
+  #   RatatuiRuby::Text.width("你好")         # => 4 (each CJK char is 2 cells)
+  #
+  #   # Mixed content
+  #   RatatuiRuby::Text.width("Hi 你好 👍")   # => 11 (2 + space + 4 + space + 2)
   module Text
     # A styled string fragment.
     #
@@ -86,5 +120,39 @@ module RatatuiRuby
         new(spans: [Span.new(content:, style: nil)], alignment:)
       end
     end
+
+    ##
+    # :method: width
+    # :call-seq: width(string) -> Integer
+    #
+    # Calculates the display width of a string in terminal cells.
+    #
+    # Layout demands precision. Terminals measure space in cells, not characters. An ASCII letter occupies one cell. A Chinese character occupies two. An emoji occupies two. Combining marks occupy zero.
+    #
+    # Measuring width manually is error-prone. You can count <tt>string.length</tt>, but that counts characters, not cells. A string with one emoji counts as 1 character but occupies 2 cells.
+    #
+    # This method returns the true display width. Use it to auto-size widgets, calculate padding, center text, or build responsive layouts.
+    #
+    # === Examples
+    #
+    #   RatatuiRuby::Text.width("Hello")        # => 5 (5 ASCII chars × 1 cell)
+    #
+    #   RatatuiRuby::Text.width("你好")         # => 4 (2 CJK chars × 2 cells)
+    #
+    #   RatatuiRuby::Text.width("Hello 👍")     # => 8 (5 ASCII + 1 space + 1 emoji × 2)
+    #
+    #   # In the Session DSL (easier)
+    #   RatatuiRuby.run do |tui|
+    #     width = tui.text_width("Hello 👍")
+    #   end
+    #
+    # [string] String to measure (String or object convertible to String)
+    # Returns: Integer (number of terminal cells the string occupies)
+    # Raises: TypeError if the argument is not a String
+    #
+    # (Native method implemented in Rust)
+    def self.width(string)
+      RatatuiRuby._text_width(string)
+    end
   end
 end

data/lib/ratatui_ruby/scrollbar_state.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Mutable state object for Scrollbar widgets.
+  #
+  # When using {Frame#render_stateful_widget}, the State object is the
+  # *single source of truth* for position and content length. Widget
+  # properties (+position+, +content_length+) are *ignored* in stateful mode.
+  #
+  # == Example
+  #
+  #   @scrollbar_state = RatatuiRuby::ScrollbarState.new(100)
+  #   @scrollbar_state.position = 25
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     scrollbar = RatatuiRuby::Scrollbar.new(orientation: :vertical_right)
+  #     frame.render_stateful_widget(scrollbar, frame.area, @scrollbar_state)
+  #   end
+  #
+  class ScrollbarState
+    ##
+    # :method: new
+    # :call-seq: new(content_length) -> ScrollbarState
+    #
+    # Creates a new ScrollbarState with the given content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: position
+    # :call-seq: position() -> Integer
+    #
+    # Returns the current scroll position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: position=
+    # :call-seq: position=(value) -> Integer
+    #
+    # Sets the current scroll position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: content_length
+    # :call-seq: content_length() -> Integer
+    #
+    # Returns the total content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: content_length=
+    # :call-seq: content_length=(value) -> Integer
+    #
+    # Sets the total content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: viewport_content_length
+    # :call-seq: viewport_content_length() -> Integer
+    #
+    # Returns the viewport content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: viewport_content_length=
+    # :call-seq: viewport_content_length=(value) -> Integer
+    #
+    # Sets the viewport content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: first
+    # :call-seq: first() -> nil
+    #
+    # Scrolls to the first position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: last
+    # :call-seq: last() -> nil
+    #
+    # Scrolls to the last position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: next
+    # :call-seq: next() -> nil
+    #
+    # Scrolls to the next position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: prev
+    # :call-seq: prev() -> nil
+    #
+    # Scrolls to the previous position.
+    #
+    # (Native method implemented in Rust)
+  end
+end