Class: RatatuiRuby::Layout::Constraint

Inherits:
Object
  • Object
show all
Defined in:
lib/ratatui_ruby/layout/constraint.rb

Overview

Defines the sizing rule for a layout section.

Flexible layouts need rules. You can’t just place widgets at absolute coordinates; they must adapt to changing terminal sizes.

This class defines the rules of engagement. It tells the layout engine exactly how much space a section requires relative to others.

Mix and match fixed lengths, percentages, ratios, and minimums. Build layouts that breathe.

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 Method Summary collapse

Instance Method Summary collapse

Class Method Details

.fill(v = 1) ⇒ Object

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).

v

Proportional weight (Integer, default: 1).



130
131
132
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 130

def self.fill(v = 1)
  new(type: :fill, value: Integer(v))
end

.from_fills(values) ⇒ Object

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.



261
262
263
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 261

def self.from_fills(values)
  values.map { |v| fill(v) }
end

.from_lengths(values) ⇒ Object

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.



173
174
175
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 173

def self.from_lengths(values)
  values.map { |v| length(v) }
end

.from_maxes(values) ⇒ Object

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.



239
240
241
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 239

def self.from_maxes(values)
  values.map { |v| max(v) }
end

.from_mins(values) ⇒ Object

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.



217
218
219
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 217

def self.from_mins(values)
  values.map { |v| min(v) }
end

.from_percentages(values) ⇒ Object

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).



195
196
197
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 195

def self.from_percentages(values)
  values.map { |v| percentage(v) }
end

.from_ratios(pairs) ⇒ Object

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 [numerator, denominator] arrays.



283
284
285
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 283

def self.from_ratios(pairs)
  pairs.map { |n, d| ratio(n, d) }
end

.length(v) ⇒ Object

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).



56
57
58
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 56

def self.length(v)
  new(type: :length, value: Integer(v))
end

.max(v) ⇒ Object

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).



109
110
111
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 109

def self.max(v)
  new(type: :max, value: Integer(v))
end

.min(v) ⇒ Object

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).



92
93
94
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 92

def self.min(v)
  new(type: :min, value: Integer(v))
end

.percentage(v) ⇒ Object

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).



73
74
75
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 73

def self.percentage(v)
  new(type: :percentage, value: Integer(v))
end

.ratio(numerator, denominator) ⇒ Object

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).



148
149
150
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 148

def self.ratio(numerator, denominator)
  new(type: :ratio, value: [Integer(numerator), Integer(denominator)])
end

Instance Method Details

#apply(length) ⇒ Object Also known as: call

Computes the size this constraint would produce given available space.

Layout engines use constraints to compute actual dimensions. Calling apply lets you preview the result without rendering.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

Constraint.percentage(50).apply(100) # => 50
Constraint.length(10).apply(100)     # => 10
Constraint.min(10).apply(5)          # => 10
Constraint.max(10).apply(15)         # => 10
Constraint.ratio(1, 4).apply(100)    # => 25

– SPDX-SnippetEnd ++

length

Available space (Integer).

Returns the computed size (Integer).



311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/ratatui_ruby/layout/constraint.rb', line 311

def apply(length)
  length = Integer(length)
  case type
  when :length
    value
  when :percentage
    (length * value) / 100
  when :min
    [value, length].max
  when :max
    [value, length].min
  when :fill
    length
  when :ratio
    numerator, denominator = value
    denominator.zero? ? 0 : (length * numerator) / denominator
  else
    length
  end
end