ratatui_ruby 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce6cd98e1b4724cd09af7f741013f441a90c571723c9925b4fd73ef91bde65aa
-  data.tar.gz: 84b2d4d8c2b6313425f497cb3e5dcc26b0bd22260b167261fbb2959b4bfca420
+  metadata.gz: c543e8590fa79c457dac22abc8c39fc2264026079196ff7d0afc1d083c9cf013
+  data.tar.gz: 8c044e43009f8ede9c66274809aacae1c7e66a503157afc6756c4890b50d899c
 SHA512:
-  metadata.gz: 7cf964a5f1d2d3ccdcf9491485c125d99d6af4f54316fe53613ef4e0571e1a934dc443ed4f19983c8325787c578ccf8e4ef7cef6ff17b5c8cc0cd58d57aa0ad5
-  data.tar.gz: 344da3ef288c3a747cd3c9d4a8c20ece64db2e5e6fcfc793a835c9a3202746cdfb2af0a37352b26b4d1fcf2933045b1c8712f02193e7bcffc6997365f6b6fec4
+  metadata.gz: dfd4c34a23e0af4dcb47c9520bae94db94cb7587f37b11662668e8f6f7e7a3148aeb0fb66ed66cb47f51898fc42da496ce50cec46ea1b286c3bcfcbe5dc43e41
+  data.tar.gz: 19871c4b3ec78afc30fc004f019b6b0ff246654ffbbe6dafb7e92cd5d1b3c4b1294ed3e836c47b70fb094dad3f5aa7927dd2b23a6cf458d571f5248fa5b0b934

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.9.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.9.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.3.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.9.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.9.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.4.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.9.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.9.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-4.0.0.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.9.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.9.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/CHANGELOG.md

@@ -18,6 +18,29 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [0.9.1] - 2026-01-08
+
+### Added
+
+- **Constraint Batch Constructors**: `Constraint` now provides batch factory methods matching upstream Ratatui for creating constraint arrays in a single call:
+  - `from_lengths([10, 20, 10])` — create multiple Length constraints
+  - `from_percentages([25, 50, 25])` — create multiple Percentage constraints
+  - `from_mins([5, 10, 5])` — create multiple Min constraints
+  - `from_maxes([20, 30, 40])` — create multiple Max constraints
+  - `from_fills([1, 2, 1])` — create multiple Fill constraints
+  - `from_ratios([[1, 4], [2, 4], [1, 4]])` — create multiple Ratio constraints
+
+- **Async Synchronization**: New `Event::Sync` event and `SyntheticEvents` module enable deterministic testing of async behavior:
+  - `Event::Sync` — synthetic event that signals runtimes (Tea, Kit) to wait for pending async operations before continuing
+  - `RatatuiRuby::SyntheticEvents` — thread-safe Ruby-only queue for synthetic events; runtimes check this alongside native events
+  - `inject_sync` test helper — injects a Sync event for deterministic async testing
+
+### Changed
+
+### Fixed
+
+### Removed
+
 ## [0.9.0] - 2026-01-08
 
 ### Added
@@ -492,6 +515,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/HEAD
+[0.9.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.9.1
 [0.9.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.9.0
 [0.8.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.8.0
 [0.7.4]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.4

data/doc/contributors/v1.0.0_blockers.md

@@ -14,7 +14,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 - Symbol Sets
   - line::Set, block::Set, scrollbar::Set
 - Layout
-  - Constraint batch constructors (6)
+  - ~~Constraint batch constructors (6)~~ ✅ DONE
   - Layout margin, spacing (2)
 - Style
   - sub_modifier, underline_color (2)
@@ -34,16 +34,10 @@ This document audits alignment between RatatuiRuby v0.7.0 and the upstream Ratat
 
 
 
-######  `Layout::Constraint` — Missing Batch Constructors
+######  `Layout::Constraint` — Batch Constructors ✅ DONE
 
-| Missing Method | Signature |
-|----------------|-----------|
-| `from_lengths` | `Constraint.from_lengths([10, 20, 30])` → `[Constraint]` |
-| `from_percentages` | `Constraint.from_percentages([25, 50, 25])` → `[Constraint]` |
-| `from_mins` | `Constraint.from_mins([5, 10, 15])` → `[Constraint]` |
-| `from_maxes` | `Constraint.from_maxes([20, 30, 40])` → `[Constraint]` |
-| `from_fills` | `Constraint.from_fills([1, 2, 1])` → `[Constraint]` |
-| `from_ratios` | `Constraint.from_ratios([[1,4], [2,4], [1,4]])` → `[Constraint]` |
+All 6 batch constructors implemented in v0.8.0:
+- `from_lengths`, `from_percentages`, `from_mins`, `from_maxes`, `from_fills`, `from_ratios`
 
 ---
 

data/examples/widget_layout_split/app.rb

@@ -124,6 +124,12 @@ class WidgetLayoutSplit
           ]
         },
       },
+      {
+        name: "Batch (from_percentages)",
+        constraints: -> (_dir) {
+          RatatuiRuby::Layout::Constraint.from_percentages([25, 50, 25])
+        },
+      },
     ]
   end
 

data/ext/ratatui_ruby/Cargo.lock

@@ -1012,7 +1012,7 @@ dependencies = [
 
 [[package]]
 name = "ratatui_ruby"
-version = "0.9.0"
+version = "0.9.1"
 dependencies = [
  "bumpalo",
  "lazy_static",

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "0.9.0"
+version = "0.9.1"
 edition = "2021"
 
 [lib]

data/ext/ratatui_ruby/src/events.rs

@@ -383,6 +383,7 @@ fn handle_key_event(key: ratatui::crossterm::event::KeyEvent) -> Result<Value, E
     if key.kind != ratatui::crossterm::event::KeyEventKind::Press {
         return Ok(ruby.qnil().into_value_with(&ruby));
     }
+
     let hash = ruby.hash_new();
     hash.aset(ruby.to_symbol("type"), ruby.to_symbol("key"))?;
 

data/lib/ratatui_ruby/event/sync.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Event
+    # Synthetic event for synchronizing async operations in tests.
+    #
+    # Testing async behavior is tricky. You inject an event, but results arrive
+    # later. By the time you assert, the async work may not have completed.
+    #
+    # When a runtime (Tea, Kit) encounters this event, it should wait for all
+    # pending async operations to complete before processing the next event.
+    # This enables deterministic testing without changing production code paths.
+    #
+    # Inject this event between user actions and assertions to ensure async
+    # results have been processed:
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   inject_key("s")           # Triggers async command
+    #   inject_sync               # Wait for command to complete
+    #   inject_key(:q)            # Quit after seeing results
+    #   Tea.run(...)
+    #   assert_snapshots("after_s_with_results")
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # This is not "test mode"—it's a real event that runtimes handle.
+    # Production apps could use it too (e.g., "ensure saves complete before quit").
+    class Sync < Event
+      # Returns true for Sync events.
+      def sync?
+        true
+      end
+
+      # Deconstructs the event for pattern matching.
+      def deconstruct_keys(keys)
+        { type: :sync }
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event.rb

@@ -111,6 +111,11 @@ module RatatuiRuby
       false
     end
 
+    # Returns true if this is a Sync event.
+    def sync?
+      false
+    end
+
     # Responds to dynamic predicate methods for key checks.
     # All non-Key events return false for any key predicate.
     def method_missing(name, *args, &block)
@@ -155,3 +160,4 @@ require_relative "event/resize"
 require_relative "event/paste"
 require_relative "event/focus_gained"
 require_relative "event/focus_lost"
+require_relative "event/sync"

data/lib/ratatui_ruby/layout/constraint.rb

@@ -148,6 +148,141 @@ module RatatuiRuby
       def self.ratio(numerator, denominator)
         new(type: :ratio, value: [Integer(numerator), Integer(denominator)])
       end
+
+      # Converts an array of lengths into an array of Length constraints.
+      #
+      # Complex layouts often use multiple fixed-size sections. Manually creating each constraint
+      # clutters the code.
+      #
+      # This method maps over the input, returning a constraint array in one call.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_lengths([10, 20, 10])
+      #   # => [Constraint.length(10), Constraint.length(20), Constraint.length(10)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers.
+      def self.from_lengths(values)
+        values.map { |v| length(v) }
+      end
+
+      # Converts an array of percentages into an array of Percentage constraints.
+      #
+      # Percentage-based layouts distribute space proportionally. This method batches the creation.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_percentages([25, 50, 25])
+      #   # => [Constraint.percentage(25), Constraint.percentage(50), Constraint.percentage(25)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers (0-100).
+      def self.from_percentages(values)
+        values.map { |v| percentage(v) }
+      end
+
+      # Converts an array of minimums into an array of Min constraints.
+      #
+      # Minimum constraints ensure sections never shrink below a threshold. Batch them here.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_mins([5, 10, 5])
+      #   # => [Constraint.min(5), Constraint.min(10), Constraint.min(5)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers.
+      def self.from_mins(values)
+        values.map { |v| min(v) }
+      end
+
+      # Converts an array of maximums into an array of Max constraints.
+      #
+      # Maximum constraints cap section sizes. Batch them here.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_maxes([20, 30, 40])
+      #   # => [Constraint.max(20), Constraint.max(30), Constraint.max(40)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers.
+      def self.from_maxes(values)
+        values.map { |v| max(v) }
+      end
+
+      # Converts an array of weights into an array of Fill constraints.
+      #
+      # Fill constraints distribute remaining space by weight. Batch them here.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_fills([1, 2, 1])
+      #   # => [Constraint.fill(1), Constraint.fill(2), Constraint.fill(1)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers.
+      def self.from_fills(values)
+        values.map { |v| fill(v) }
+      end
+
+      # Converts an array of ratio pairs into an array of Ratio constraints.
+      #
+      # Ratio constraints define exact fractions of space. Batch them here.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_ratios([[1, 4], [2, 4], [1, 4]])
+      #   # => [Constraint.ratio(1, 4), Constraint.ratio(2, 4), Constraint.ratio(1, 4)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [pairs] Enumerable of <tt>[numerator, denominator]</tt> arrays.
+      def self.from_ratios(pairs)
+        pairs.map { |n, d| ratio(n, d) }
+      end
     end
   end
 end

data/lib/ratatui_ruby/synthetic_events.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  ##
+  # Ruby-only event queue for synthetic events.
+  #
+  # Native events flow through the Rust backend. Synthetic events bypass it.
+  # Runtimes (Tea, Kit) check this queue and handle events like
+  # <tt>Event::Sync</tt> specially.
+  #
+  # *For runtime authors:* Check <tt>pending?</tt> each loop iteration after
+  # polling native events. When true, pop the event and handle it. For
+  # <tt>Event::Sync</tt>, wait for pending threads and process background
+  # results before continuing.
+  #
+  # *For app developers:* Push <tt>Event::Sync</tt> when you need async
+  # results before continuing. The runtime will block until all pending
+  # work completes. Use this for "ensure saves complete before quit."
+  #
+  # *For test authors:* Use <tt>inject_sync</tt> between events to create
+  # synchronization points. This enables deterministic testing of async
+  # behavior.
+  #
+  # === Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   # Production: ensure async saves finish before exiting
+  #   RatatuiRuby::SyntheticEvents.push(RatatuiRuby::Event::Sync.new)
+  #
+  #   # Runtime authors: check in your event loop
+  #   if RatatuiRuby::SyntheticEvents.pending?
+  #     event = RatatuiRuby::SyntheticEvents.pop
+  #     handle_sync if event.sync?
+  #   end
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  module SyntheticEvents
+    @queue = []
+    @mutex = Mutex.new
+
+    class << self
+      ##
+      # Pushes an event to the synthetic queue.
+      #
+      # [event] An <tt>Event</tt> object (typically <tt>Event::Sync</tt>).
+      def push(event)
+        @mutex.synchronize { @queue << event }
+      end
+
+      ##
+      # Pops an event from the synthetic queue.
+      #
+      # Returns the oldest pending event, or <tt>nil</tt> if empty.
+      def pop
+        @mutex.synchronize { @queue.shift }
+      end
+
+      ##
+      # Clears all pending synthetic events.
+      #
+      # Test helpers call this during teardown to reset state between tests.
+      def clear
+        @mutex.synchronize { @queue.clear }
+      end
+
+      ##
+      # Checks for pending synthetic events.
+      #
+      # Returns <tt>true</tt> if the queue has events waiting.
+      def pending?
+        @mutex.synchronize { !@queue.empty? }
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/test_helper/event_injection.rb

@@ -88,6 +88,9 @@ module RatatuiRuby
           RatatuiRuby.inject_test_event("focus_gained", {})
         when RatatuiRuby::Event::FocusLost
           RatatuiRuby.inject_test_event("focus_lost", {})
+        when RatatuiRuby::Event::Sync
+          # Sync events use the engine-level synthetic queue
+          RatatuiRuby::SyntheticEvents.push(event)
         else
           raise ArgumentError, "Unknown event type: #{event.class}"
         end
@@ -198,6 +201,31 @@ module RatatuiRuby
         end
       end
       alias inject_key inject_keys
+
+      ##
+      # Injects a Sync event.
+      #
+      # When a runtime (Tea, Kit) encounters this event, it should wait for all
+      # pending async operations to complete before processing the next event.
+      # This enables deterministic testing of async behavior.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   inject_key("s")           # Triggers async command
+      #   inject_sync               # Wait for command to complete
+      #   inject_key(:q)            # Quit after seeing results
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def inject_sync
+        inject_event(RatatuiRuby::Event::Sync.new)
+      end
     end
   end
 end

data/lib/ratatui_ruby/version.rb

@@ -8,5 +8,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "0.9.0"
+  VERSION = "0.9.1"
 end

data/lib/ratatui_ruby.rb

@@ -31,6 +31,9 @@ require_relative "ratatui_ruby/terminal_lifecycle"
 # TUI facade (for external instantiation and caching)
 require_relative "ratatui_ruby/tui"
 
+# Synthetic events queue (for async synchronization)
+require_relative "ratatui_ruby/synthetic_events"
+
 begin
   require "ratatui_ruby/ratatui_ruby"
 rescue LoadError
@@ -120,16 +123,17 @@ module RatatuiRuby
     #++
     class Safety < Error; end
 
-    # State invariant violation.
+    # Invariant violation.
     #
-    # The library has rules about valid state transitions.
-    # Calling methods in the wrong order or state breaks invariants.
+    # The library enforces rules about valid states and contracts.
+    # Breaking these rules raises this error.
     #
-    # This error signals you violated a state machine contract.
-    # The program state doesn't allow this operation right now.
+    # Common causes:
+    # - Calling methods in the wrong order (e.g., \`init_terminal\` twice)
+    # - Callable return type mismatch (e.g., view returns \`nil\` instead of a widget)
     #
-    # To resolve, check `terminal_active?` or restructure the
-    # code to ensure methods are called in the expected order.
+    # To resolve, check the method's documented contract. Ensure
+    # state preconditions are met and return types are correct.
     #
     # === Example
     #

data/sig/ratatui_ruby/schema/constraint.rbs

@@ -18,5 +18,13 @@ module RatatuiRuby
     def self.fill: (?Numeric) -> Constraint
     def self.ratio: (Numeric, Numeric) -> Constraint
     def self.new: (type: Symbol, value: (Integer | Array[Integer])) -> Constraint
+
+    # Batch constructors
+    def self.from_lengths: (Enumerable[Numeric]) -> Array[Constraint]
+    def self.from_percentages: (Enumerable[Numeric]) -> Array[Constraint]
+    def self.from_mins: (Enumerable[Numeric]) -> Array[Constraint]
+    def self.from_maxes: (Enumerable[Numeric]) -> Array[Constraint]
+    def self.from_fills: (Enumerable[Numeric]) -> Array[Constraint]
+    def self.from_ratios: (Enumerable[[Numeric, Numeric]]) -> Array[Constraint]
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Kerrick Long
@@ -315,6 +315,7 @@ files:
 - lib/ratatui_ruby/event/none.rb
 - lib/ratatui_ruby/event/paste.rb
 - lib/ratatui_ruby/event/resize.rb
+- lib/ratatui_ruby/event/sync.rb
 - lib/ratatui_ruby/frame.rb
 - lib/ratatui_ruby/layout.rb
 - lib/ratatui_ruby/layout/constraint.rb
@@ -355,6 +356,7 @@ files:
 - lib/ratatui_ruby/scrollbar_state.rb
 - lib/ratatui_ruby/style.rb
 - lib/ratatui_ruby/style/style.rb
+- lib/ratatui_ruby/synthetic_events.rb
 - lib/ratatui_ruby/table_state.rb
 - lib/ratatui_ruby/terminal_lifecycle.rb
 - lib/ratatui_ruby/test_helper.rb