ratatui_ruby 0.8.0 → 0.9.0

data/lib/ratatui_ruby/frame.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -30,13 +30,26 @@ module RatatuiRuby
   #
   # Basic usage with a single widget:
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   RatatuiRuby.draw do |frame|
   #     paragraph = RatatuiRuby::Widgets::Paragraph.new(text: "Hello, world!")
   #     frame.render_widget(paragraph, frame.area)
   #   end
   #
+  #--
+  # SPDX-SnippetEnd
+  #++
   # Using Layout.split for multi-region layouts:
   #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
   #   RatatuiRuby.draw do |frame|
   #     sidebar, main = RatatuiRuby::Layout.split(
   #       frame.area,
@@ -53,6 +66,9 @@ module RatatuiRuby
   #     # Store rects for hit testing — no duplication!
   #     @regions = { sidebar: sidebar, main: main }
   #   end
+  #--
+  # SPDX-SnippetEnd
+  #++
   class Frame
     ##
     # :method: area
@@ -65,10 +81,18 @@ module RatatuiRuby
     #
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   RatatuiRuby.draw do |frame|
     #     puts "Terminal size: #{frame.area.width}x#{frame.area.height}"
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # (Native method implemented in Rust)
 
     ##
@@ -83,15 +107,31 @@ module RatatuiRuby
     # [widget]
     #   The widget to render (Paragraph, Layout, List, Table, etc.).
     # [area]
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   A Rect specifying where to render the widget.
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   RatatuiRuby.draw do |frame|
     #     para = RatatuiRuby::Widgets::Paragraph.new(text: "Content")
     #     frame.render_widget(para, frame.area)
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # (Native method implemented in Rust)
 
     ##
@@ -116,10 +156,23 @@ module RatatuiRuby
     # [area]
     #   The Rect area to render into.
     # [state]
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   The mutable state object (Output) (e.g., RatatuiRuby::ListState).
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === Example
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   # Initialize state once (outside the loop)
     #   @list_state = RatatuiRuby::ListState.new
     #
@@ -131,6 +184,9 @@ module RatatuiRuby
     #   # Read back the offset calculated by Ratatui
     #   puts @list_state.offset
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # (Native method implemented in Rust)
 
     ##
@@ -151,12 +207,25 @@ module RatatuiRuby
     # [x]
     #   Column position (<tt>0</tt> = leftmost column).
     # [y]
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   Row position (<tt>0</tt> = topmost row).
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # === Example
     #
     # Position the cursor at the end of typed text in a login form:
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   PREFIX = "Username: [ "
     #   username = "alice"
     #
@@ -175,6 +244,9 @@ module RatatuiRuby
     #     frame.set_cursor_position(cursor_x, cursor_y)
     #   end
     #
+    #--
+    # SPDX-SnippetEnd
+    #++
     # See also:
     # - {Component-based implementation using Frame API}[link:/examples/app_color_picker/app_rb.html]
     # - {Declarative implementation using Tree API}[link:/examples/app_login_form/app_rb.html]

data/lib/ratatui_ruby/layout/constraint.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -17,10 +17,18 @@ module RatatuiRuby
     #
     # === Examples
     #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
     #   Layout::Constraint.length(5)      # Exactly 5 cells
     #   Layout::Constraint.percentage(50) # Half the available space
     #   Layout::Constraint.min(10)        # At least 10 cells, maybe more
     #   Layout::Constraint.fill(1)        # Fill remaining space (weight 1)
+    #--
+    # SPDX-SnippetEnd
+    #++
     class Constraint < Data.define(:type, :value)
       ##
       # :attr_reader: type
@@ -34,8 +42,16 @@ module RatatuiRuby
 
       # Requests a fixed size.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Layout::Constraint.length(10) # 10 characters wide/high
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [v] Number of cells (Integer).
       def self.length(v)
         new(type: :length, value: Integer(v))
@@ -43,8 +59,16 @@ module RatatuiRuby
 
       # Requests a percentage of available space.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Layout::Constraint.percentage(25) # 25% of the area
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [v] Percentage 0-100 (Integer).
       def self.percentage(v)
         new(type: :percentage, value: Integer(v))
@@ -52,8 +76,16 @@ module RatatuiRuby
 
       # Enforces a minimum size.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Layout::Constraint.min(5) # At least 5 cells
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # This section will grow if space permits, but never shrink below +v+.
       #
       # [v] Minimum cells (Integer).
@@ -63,8 +95,16 @@ module RatatuiRuby
 
       # Enforces a maximum size.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Layout::Constraint.max(10) # At most 10 cells
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [v] Maximum cells (Integer).
       def self.max(v)
         new(type: :max, value: Integer(v))
@@ -72,9 +112,17 @@ module RatatuiRuby
 
       # Fills remaining space proportionally.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Layout::Constraint.fill(1) # Equal share
       #   Layout::Constraint.fill(2) # Double share
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # Fill constraints distribute any space left after satisfying strict rules.
       # They behave like flex-grow. A fill(2) takes twice as much space as a fill(1).
       #
@@ -85,8 +133,16 @@ module RatatuiRuby
 
       # Requests a specific ratio of the total space.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Layout::Constraint.ratio(1, 3) # 1/3rd of the area
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [numerator] Top part of fraction (Integer).
       # [denominator] Bottom part of fraction (Integer).
       def self.ratio(numerator, denominator)

data/lib/ratatui_ruby/layout/layout.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 module RatatuiRuby
@@ -52,6 +52,35 @@ module RatatuiRuby
       # :nodoc:
       FLEX_MODES = %i[legacy start center end space_between space_around space_evenly].freeze
 
+      ##
+      # Direction: split vertically (top to bottom).
+      DIRECTION_VERTICAL = :vertical
+      ##
+      # Direction: split horizontally (left to right).
+      DIRECTION_HORIZONTAL = :horizontal
+
+      ##
+      # Flex: use legacy sizing (default).
+      FLEX_LEGACY = :legacy
+      ##
+      # Flex: align to start.
+      FLEX_START = :start
+      ##
+      # Flex: center alignment.
+      FLEX_CENTER = :center
+      ##
+      # Flex: align to end.
+      FLEX_END = :end
+      ##
+      # Flex: space between elements.
+      FLEX_SPACE_BETWEEN = :space_between
+      ##
+      # Flex: space around elements.
+      FLEX_SPACE_AROUND = :space_around
+      ##
+      # Flex: space evenly between elements.
+      FLEX_SPACE_EVENLY = :space_evenly
+
       # Creates a new Layout.
       #
       # [direction]
@@ -71,6 +100,11 @@ module RatatuiRuby
       # This is a pure calculation helper for hit testing. It computes where
       # widgets *would* be placed without actually rendering them.
       #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   rects = Layout::Layout.split(
       #     area,
       #     direction: :horizontal,
@@ -78,6 +112,9 @@ module RatatuiRuby
       #   )
       #   left, right = rects
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # [area]
       #   The area to split. Can be a <tt>Rect</tt> or a <tt>Hash</tt> containing <tt>:x</tt>, <tt>:y</tt>, <tt>:width</tt>, and <tt>:height</tt>.
       # [direction]
@@ -85,8 +122,16 @@ module RatatuiRuby
       # [constraints]
       #   Array of <tt>Constraint</tt> objects defining section sizes.
       # [flex]
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
       #   Flex mode for spacing (default: <tt>:legacy</tt>).
       #
+      #--
+      # SPDX-SnippetEnd
+      #++
       # Returns an Array of <tt>Rect</tt> objects.
       def self.split(area, direction: :vertical, constraints:, flex: :legacy)
         # Duck-typing: If it lacks geometry methods but can be a Hash, convert it.