ratatui_ruby 0.5.0 → 0.7.0

data/lib/ratatui_ruby/event/key/modifier.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    class Key < Event
+      # Methods and logic for modifier keys.
+      module Modifier
+        # Returns true if CTRL is held OR if this is a left_control/right_control key event.
+        def ctrl?
+          @modifiers.include?("ctrl") || @code == "left_control" || @code == "right_control"
+        end
+
+        # Alias for {#ctrl?}.
+        alias control? ctrl?
+
+        # Returns true if ALT is held OR if this is a left_alt/right_alt key event.
+        def alt?
+          @modifiers.include?("alt") || @code == "left_alt" || @code == "right_alt"
+        end
+
+        # Alias for {#alt?}.
+        alias option? alt?
+
+        # Returns true if SHIFT is held OR if this is a left_shift/right_shift key event.
+        def shift?
+          @modifiers.include?("shift") || @code == "left_shift" || @code == "right_shift"
+        end
+
+        # Returns true if SUPER is held OR if this is a left_super/right_super key event.
+        # Also responds to platform aliases: win?, command?, cmd?, tux?
+        def super?
+          @modifiers.include?("super") || @code == "left_super" || @code == "right_super"
+        end
+
+        # Alias for {#super?}.
+        alias win? super?
+        # Alias for {#super?}.
+        alias command? super?
+        # Alias for {#super?}.
+        alias cmd? super?
+        # Alias for {#super?}.
+        alias tux? super?
+
+        # Returns true if HYPER is held OR if this is a left_hyper/right_hyper key event.
+        def hyper?
+          @modifiers.include?("hyper") || @code == "left_hyper" || @code == "right_hyper"
+        end
+
+        # Returns true if META is held OR if this is a left_meta/right_meta key event.
+        def meta?
+          @modifiers.include?("meta") || @code == "left_meta" || @code == "right_meta"
+        end
+
+        # Returns true if this is a modifier key event.
+        #
+        # Some applications need to know if an event represents a generic key
+        # press or a specific modifier key (like CTRL or ALT) being pressed on
+        # its own.
+        #
+        # This method identifies if the key event itself is a modifier key.
+        #
+        # === Example
+        #
+        #   if event.modifier?
+        #     # Handle solo modifier key press
+        #   end
+        def modifier?
+          @kind == :modifier
+        end
+
+        # Handles modifier-specific DWIM logic for method_missing.
+        private def match_modifier_dwim?(key_name, key_sym)
+          # Platform modifier aliases
+          modifier_aliases = {
+            win: "super",
+            command: "super",
+            cmd: "super",
+            tux: "super",
+          }.freeze
+
+          target_modifier = modifier_aliases[key_sym]
+          if target_modifier
+            return true if @modifiers.include?(target_modifier)
+            return true if @code == "left_#{target_modifier}" || @code == "right_#{target_modifier}"
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/key/navigation.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    class Key < Event
+      # Methods and logic for navigation keys.
+      module Navigation
+        # Returns true if this is a standard key.
+        #
+        # Standard keys include: characters, Enter, Tab, arrow keys, navigation keys.
+        #
+        #   event.standard? # => true for "a", "enter", "up", etc.
+        def standard?
+          @kind == :standard
+        end
+
+        # Alias for {#standard?}.
+        #
+        # Provided for semantic clarity when checking if a key has no special category.
+        #
+        #   event.unmodified? # => true for standard keys like "a", "enter", "up"
+        alias unmodified? standard?
+
+        # Handles navigation-specific DWIM logic for method_missing.
+        private def match_navigation_dwim?(key_name, key_sym)
+          # DWIM: reverse_tab? matches both BackTab key and Shift+Tab combo
+          if key_name == "reverse_tab"
+            return true if @code == "back_tab"
+            return true if @code == "tab" && @modifiers.include?("shift")
+          end
+
+          # DWIM: Check explicit aliases
+          navigation_aliases = {
+            return: "enter",
+            back: "backspace",
+            del: "delete",
+            ins: "insert",
+            pgup: "page_up",
+            pageup: "page_up",
+            pgdn: "page_down",
+            pagedown: "page_down",
+          }.freeze
+
+          target_code = navigation_aliases[key_sym]
+          return true if target_code && @code == target_code && @modifiers.empty?
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/key/system.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    class Key < Event
+      # Methods and logic for system and function keys.
+      module System
+        # Returns true if this is a system key.
+        #
+        # System keys include: Esc, CapsLock, ScrollLock, NumLock, PrintScreen, Pause, Menu, KeypadBegin.
+        #
+        #   event.system? # => true for pause, esc, caps_lock, etc.
+        def system?
+          @kind == :system
+        end
+
+        # Returns true if this is a function key (F1-F24).
+        #
+        #   event.function? # => true for f1, f2, ..., f24
+        def function?
+          @kind == :function
+        end
+
+        # Handles system-specific DWIM logic for method_missing.
+        private def match_system_dwim?(key_name, key_sym)
+          system_aliases = {
+            scrlk: "scroll_lock",
+            scroll: "scroll_lock",
+            prtsc: "print_screen",
+            print: "print_screen",
+            escape: "esc",
+          }.freeze
+
+          target_code = system_aliases[key_sym]
+          return true if target_code && @code == target_code && @modifiers.empty?
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/key.rb

@@ -3,6 +3,12 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+require_relative "key/character"
+require_relative "key/media"
+require_relative "key/modifier"
+require_relative "key/navigation"
+require_relative "key/system"
+
 module RatatuiRuby
   class Event
     # Captures a keyboard interaction.
@@ -33,7 +39,34 @@ module RatatuiRuby
     #   in type: :key, code: "c", modifiers: ["ctrl"]
     #     exit
     #   end
+    #
+    # === Terminal Compatibility
+    #
+    # Some key combinations never reach your application. Terminal emulators intercept them for
+    # built-in features like tab switching. Common culprits:
+    #
+    # * Ctrl+PageUp/PageDown (tab switching in Terminal.app, iTerm2)
+    # * Ctrl+Tab (tab switching)
+    # * Cmd+key combinations (macOS system shortcuts)
+    #
+    # If modifiers appear missing, test with a different terminal. Kitty, WezTerm, and Alacritty
+    # pass more keys through. See <tt>doc/terminal_limitations.md</tt> for details.
+    #
+    # === Enhanced Keys (Kitty Protocol)
+    #
+    # Terminals supporting the Kitty keyboard protocol report additional keys:
+    #
+    # * Media keys: <tt>:play</tt>, <tt>:play_pause</tt>, <tt>:track_next</tt>, <tt>:mute_volume</tt>
+    # * Individual modifiers: <tt>:left_shift</tt>, <tt>:right_control</tt>, <tt>:left_super</tt>
+    #
+    # These keys will not work in Terminal.app, iTerm2, or GNOME Terminal.
     class Key < Event
+      include Character
+      include Media
+      include Modifier
+      include Navigation
+      include System
+
       # The key code (e.g., <tt>"a"</tt>, <tt>"enter"</tt>, <tt>"up"</tt>).
       #
       #   puts event.code # => "enter"
@@ -44,6 +77,15 @@ module RatatuiRuby
       #   puts event.modifiers # => ["ctrl", "shift"]
       attr_reader :modifiers
 
+      # The category of the key.
+      #
+      # One of: <tt>:standard</tt>, <tt>:function</tt>, <tt>:media</tt>, <tt>:modifier</tt>, <tt>:system</tt>.
+      #
+      # This allows grouping keys by their logical type without parsing the code string.
+      #
+      #   event.kind # => :media
+      attr_reader :kind
+
       # Returns true for Key events.
       #
       #   event.key?    # => true
@@ -59,17 +101,21 @@ module RatatuiRuby
       #   The key code (String).
       # [modifiers]
       #   List of modifiers (Array<String>).
-      def initialize(code:, modifiers: [])
-        @code = code
-        @modifiers = modifiers.sort
+      # [kind]
+      #   The key category (Symbol). One of: <tt>:standard</tt>, <tt>:function</tt>,
+      #   <tt>:media</tt>, <tt>:modifier</tt>, <tt>:system</tt>. Defaults to <tt>:standard</tt>.
+      def initialize(code:, modifiers: [], kind: :standard)
+        @code = code.freeze
+        @modifiers = modifiers.map(&:freeze).sort.freeze
+        @kind = kind
       end
 
       # Compares the event with another object.
       #
       # - If +other+ is a +Symbol+, compares against #to_sym.
       # - If +other+ is a +String+, compares against #to_s.
-      # - Otherwise, performs standard equality check.
-      # - Otherwise, compares internal state (code + modifiers).
+      # - If +other+ is a +Key+, compares as a value object.
+      # - Otherwise, compares using standard equality.
       def ==(other)
         case other
         when Symbol
@@ -91,9 +137,25 @@ module RatatuiRuby
       # === Supported Keys
       #
       # [Standard]
-      #   <tt>:enter</tt>, <tt>:backspace</tt>, <tt>:tab</tt>, <tt>:esc</tt>, <tt>:page_up</tt>, <tt>:page_down</tt>, <tt>:home</tt>, <tt>:end</tt>, <tt>:delete</tt>, <tt>:insert</tt>, <tt>:f1</tt>..<tt>:f12</tt>
+      #   <tt>:enter</tt>, <tt>:backspace</tt>, <tt>:tab</tt>, <tt>:back_tab</tt>, <tt>:esc</tt>, <tt>:null</tt>
       # [Navigation]
-      #   <tt>:up</tt>, <tt>:down</tt>, <tt>:left</tt>, <tt>:right</tt>
+      #   <tt>:up</tt>, <tt>:down</tt>, <tt>:left</tt>, <tt>:right</tt>, <tt>:home</tt>, <tt>:end</tt>,
+      #   <tt>:page_up</tt>, <tt>:page_down</tt>, <tt>:insert</tt>, <tt>:delete</tt>
+      # [Function Keys]
+      #   <tt>:f1</tt> through <tt>:f12</tt> (and beyond, e.g. <tt>:f24</tt>)
+      # [Lock Keys]
+      #   <tt>:caps_lock</tt>, <tt>:scroll_lock</tt>, <tt>:num_lock</tt>
+      # [System Keys]
+      #   <tt>:print_screen</tt>, <tt>:pause</tt>, <tt>:menu</tt>, <tt>:keypad_begin</tt>
+      # [Media Keys]
+      #   <tt>:play</tt>, <tt>:media_pause</tt>, <tt>:play_pause</tt>, <tt>:reverse</tt>, <tt>:stop</tt>,
+      #   <tt>:fast_forward</tt>, <tt>:rewind</tt>, <tt>:track_next</tt>, <tt>:track_previous</tt>,
+      #   <tt>:record</tt>, <tt>:lower_volume</tt>, <tt>:raise_volume</tt>, <tt>:mute_volume</tt>
+      # [Modifier Keys]
+      #   <tt>:left_shift</tt>, <tt>:left_control</tt>, <tt>:left_alt</tt>, <tt>:left_super</tt>,
+      #   <tt>:left_hyper</tt>, <tt>:left_meta</tt>, <tt>:right_shift</tt>, <tt>:right_control</tt>,
+      #   <tt>:right_alt</tt>, <tt>:right_super</tt>, <tt>:right_hyper</tt>, <tt>:right_meta</tt>,
+      #   <tt>:iso_level3_shift</tt>, <tt>:iso_level5_shift</tt>
       # [Characters]
       #   <tt>:a</tt>, <tt>:b</tt>, <tt>:1</tt>, <tt>:space</tt>, etc.
       #
@@ -131,46 +193,7 @@ module RatatuiRuby
 
       # Returns inspection string.
       def inspect
-        "#<#{self.class} code=#{@code.inspect} modifiers=#{@modifiers.inspect}>"
-      end
-
-      # Returns true if CTRL is held.
-      def ctrl?
-        @modifiers.include?("ctrl")
-      end
-
-      # Returns true if ALT is held.
-      def alt?
-        @modifiers.include?("alt")
-      end
-
-      # Returns true if SHIFT is held.
-      def shift?
-        @modifiers.include?("shift")
-      end
-
-      # Returns true if the key represents a single printable character.
-      #
-      #   RatatuiRuby::Event::Key.new(code: "a").text?       # => true
-      #   RatatuiRuby::Event::Key.new(code: "enter").text?   # => false
-      #   RatatuiRuby::Event::Key.new(code: "space").text?   # => false ("space" is not 1 char, " " is)
-      def text?
-        @code.length == 1
-      end
-
-      # Returns the key as a printable character (if applicable).
-      #
-      # [Printable Characters]
-      #   Returns the character itself (e.g., <tt>"a"</tt>, <tt>"1"</tt>, <tt>" "</tt>).
-      # [Special Keys]
-      #   Returns an empty string (e.g., <tt>"enter"</tt>, <tt>"up"</tt>, <tt>"f1"</tt>).
-      #
-      # This is equivalent to +to_s+.
-      #
-      #   RatatuiRuby::Event::Key.new(code: "a").char      # => "a"
-      #   RatatuiRuby::Event::Key.new(code: "enter").char  # => ""
-      def char
-        to_s
+        "#<#{self.class} code=#{@code.inspect} modifiers=#{@modifiers.inspect} kind=#{@kind.inspect}>"
       end
 
       # Supports dynamic key predicate methods via method_missing.
@@ -184,12 +207,47 @@ module RatatuiRuby
       #
       # The method name is converted to a symbol and compared against the event.
       # This works for any key code or modifier+key combination.
+      #
+      # === Smart Predicates (DWIM)
+      #
+      # For convenience, generic predicates match both system and media variants:
+      #
+      #   event.pause?      # => true for BOTH system "pause" AND "media_pause"
+      #   event.play?       # => true for "media_play"
+      #   event.stop?       # => true for "media_stop"
+      #
+      # This "Do What I Mean" behavior reduces boilerplate when you just want to
+      # respond to a conceptual action (e.g., "pause the playback") regardless of
+      # whether the user pressed a keyboard key or a media button.
+      #
+      # For strict matching, use the full predicate or compare the code directly:
+      #
+      #   event.media_pause?  # => true ONLY for media pause
+      #   event.code == "pause"  # => true ONLY for system pause
       def method_missing(name, *args, &block)
         if name.to_s.end_with?("?")
-          key_sym = name.to_s[0...-1].to_sym
-          return self == key_sym
+          key_name = name.to_s[0...-1]
+          key_sym = key_name.to_sym
+
+          # Fast path: Exact match (e.g., media_pause? for media_pause)
+          return true if self == key_sym
+
+          # Delegate category-specific DWIM logic to mixins
+          return true if match_media_dwim?(key_name)
+          return true if match_modifier_dwim?(key_name, key_sym)
+          return true if match_navigation_dwim?(key_name, key_sym)
+          return true if match_system_dwim?(key_name, key_sym)
+
+          # DWIM: Universal underscore-insensitivity
+          # Normalize both predicate and code by stripping underscores
+          normalized_predicate = key_name.delete("_")
+          normalized_code = @code.delete("_")
+          return true if normalized_predicate == normalized_code && @modifiers.empty?
+
+          false
+        else
+          super
         end
-        super
       end
 
       # Declares that this class responds to dynamic predicate methods.
@@ -202,9 +260,11 @@ module RatatuiRuby
       #   case event
       #   in type: :key, code: "c", modifiers: ["ctrl"]
       #     puts "Ctrl+C pressed"
+      #   in type: :key, kind: :media
+      #     puts "Media key pressed"
       #   end
       def deconstruct_keys(keys)
-        { type: :key, code: @code, modifiers: @modifiers }
+        { type: :key, code: @code, modifiers: @modifiers, kind: @kind }
       end
     end
   end

data/lib/ratatui_ruby/event/mouse.rb

@@ -67,11 +67,11 @@ module RatatuiRuby
       # [modifiers]
       #   List of modifiers (Array<String>).
       def initialize(kind:, x:, y:, button:, modifiers: [])
-        @kind = kind
+        @kind = kind.freeze
         @x = x
         @y = y
-        @button = button || "none"
-        @modifiers = modifiers.sort
+        @button = (button || "none").freeze
+        @modifiers = modifiers.map(&:freeze).sort.freeze
       end
 
       # Returns true if mouse button was pressed down.

data/lib/ratatui_ruby/event/paste.rb

@@ -47,7 +47,7 @@ module RatatuiRuby
       # [content]
       #   Pasted text (String).
       def initialize(content:)
-        @content = content
+        @content = content.freeze
       end
 
       # Deconstructs the event for pattern matching.

data/lib/ratatui_ruby/frame.rb

@@ -16,12 +16,20 @@ module RatatuiRuby
   # Use it inside a <tt>RatatuiRuby.draw</tt> block to render widgets with full
   # control over placement.
   #
+  # == Thread/Ractor Safety
+  #
+  # Frame is an *I/O handle*, not a data object. It has side effects
+  # (render_widget, set_cursor_position) and is intentionally *not*
+  # Ractor-shareable. Passing it to helper methods during the draw block is
+  # fine. However, do not include it in immutable Models/Messages or pass
+  # it to other Ractors. Frame is only valid during the draw block's execution.
+  #
   # === Examples
   #
   # Basic usage with a single widget:
   #
   #   RatatuiRuby.draw do |frame|
-  #     paragraph = RatatuiRuby::Paragraph.new(text: "Hello, world!")
+  #     paragraph = RatatuiRuby::Widgets::Paragraph.new(text: "Hello, world!")
   #     frame.render_widget(paragraph, frame.area)
   #   end
   #
@@ -32,8 +40,8 @@ module RatatuiRuby
   #       frame.area,
   #       direction: :horizontal,
   #       constraints: [
-  #         RatatuiRuby::Constraint.length(20),
-  #         RatatuiRuby::Constraint.fill(1)
+  #         RatatuiRuby::Layout::Constraint.length(20),
+  #         RatatuiRuby::Layout::Constraint.fill(1)
   #       ]
   #     )
   #
@@ -78,10 +86,98 @@ module RatatuiRuby
     # === Example
     #
     #   RatatuiRuby.draw do |frame|
-    #     para = RatatuiRuby::Paragraph.new(text: "Content")
+    #     para = RatatuiRuby::Widgets::Paragraph.new(text: "Content")
     #     frame.render_widget(para, frame.area)
     #   end
     #
     # (Native method implemented in Rust)
+
+    ##
+    # :method: render_stateful_widget
+    # :call-seq: render_stateful_widget(widget, area, state) -> nil
+    #
+    # Renders a widget with persistent state.
+    #
+    # Some UI components (like List or Table) have **runtime status** (Status) that
+    # changes during rendering, such as the current scroll offset.
+    #
+    # Since Widget definitions (Configuration Definition) are immutable inputs,
+    # you must pass a separate mutable State object (Output Status) to capture
+    # these changes.
+    #
+    # Note: The Widget configuration is *always* required. The State object is
+    # only used for specific widgets that need to persist runtime status.
+    #
+    #
+    # [widget]
+    #   The immutable widget configuration (Input) (e.g., RatatuiRuby::List).
+    # [area]
+    #   The Rect area to render into.
+    # [state]
+    #   The mutable state object (Output) (e.g., RatatuiRuby::ListState).
+    #
+    # === Example
+    #
+    #   # Initialize state once (outside the loop)
+    #   @list_state = RatatuiRuby::ListState.new
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     list = RatatuiRuby::Widgets::List.new(items: ["A", "B"])
+    #     frame.render_stateful_widget(list, frame.area, @list_state)
+    #   end
+    #
+    #   # Read back the offset calculated by Ratatui
+    #   puts @list_state.offset
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: set_cursor_position
+    # :call-seq: set_cursor_position(x, y) -> nil
+    #
+    # Positions the blinking cursor at the given coordinates.
+    #
+    # Text input fields show users where typed characters will appear. Without
+    # a visible cursor, users cannot tell if the input is focused or where text
+    # will insert.
+    #
+    # This method moves the terminal cursor to a specific cell. Coordinates are
+    # 0-indexed from the terminal's top-left corner.
+    #
+    # Use it when building login forms, search bars, or command palettes.
+    #
+    # [x]
+    #   Column position (<tt>0</tt> = leftmost column).
+    # [y]
+    #   Row position (<tt>0</tt> = topmost row).
+    #
+    # === Example
+    #
+    # Position the cursor at the end of typed text in a login form:
+    #
+    #   PREFIX = "Username: [ "
+    #   username = "alice"
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     # Render the input field
+    #     prompt = RatatuiRuby::Widgets::Paragraph.new(
+    #       text: "#{PREFIX}#{username} ]",
+    #       block: RatatuiRuby::Widgets::Block.new(borders: :all)
+    #     )
+    #     frame.render_widget(prompt, frame.area)
+    #
+    #     # Position cursor after the typed text
+    #     # Account for border (1) + prefix length + username length
+    #     cursor_x = 1 + PREFIX.length + username.length
+    #     cursor_y = 1  # First line inside border
+    #     frame.set_cursor_position(cursor_x, cursor_y)
+    #   end
+    #
+    # 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]
+    # - RatatuiRuby::Cursor (Tree API alternative)
+    #
+    # (Native method implemented in Rust)
   end
 end

data/lib/ratatui_ruby/layout/constraint.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Layout
+    # 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
+    #
+    #   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)
+    class Constraint < Data.define(:type, :value)
+      ##
+      # :attr_reader: type
+      # The type of constraint.
+      #
+      # <tt>:length</tt>, <tt>:percentage</tt>, <tt>:min</tt>, <tt>:max</tt>, <tt>:fill</tt>, or <tt>:ratio</tt>.
+
+      ##
+      # :attr_reader: value
+      # The numeric value (or array for ratio) associated with the rule.
+
+      # Requests a fixed size.
+      #
+      #   Layout::Constraint.length(10) # 10 characters wide/high
+      #
+      # [v] Number of cells (Integer).
+      def self.length(v)
+        new(type: :length, value: Integer(v))
+      end
+
+      # Requests a percentage of available space.
+      #
+      #   Layout::Constraint.percentage(25) # 25% of the area
+      #
+      # [v] Percentage 0-100 (Integer).
+      def self.percentage(v)
+        new(type: :percentage, value: Integer(v))
+      end
+
+      # Enforces a minimum size.
+      #
+      #   Layout::Constraint.min(5) # At least 5 cells
+      #
+      # This section will grow if space permits, but never shrink below +v+.
+      #
+      # [v] Minimum cells (Integer).
+      def self.min(v)
+        new(type: :min, value: Integer(v))
+      end
+
+      # Enforces a maximum size.
+      #
+      #   Layout::Constraint.max(10) # At most 10 cells
+      #
+      # [v] Maximum cells (Integer).
+      def self.max(v)
+        new(type: :max, value: Integer(v))
+      end
+
+      # Fills remaining space proportionally.
+      #
+      #   Layout::Constraint.fill(1) # Equal share
+      #   Layout::Constraint.fill(2) # Double share
+      #
+      # 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).
+      def self.fill(v = 1)
+        new(type: :fill, value: Integer(v))
+      end
+
+      # Requests a specific ratio of the total space.
+      #
+      #   Layout::Constraint.ratio(1, 3) # 1/3rd of the area
+      #
+      # [numerator] Top part of fraction (Integer).
+      # [denominator] Bottom part of fraction (Integer).
+      def self.ratio(numerator, denominator)
+        new(type: :ratio, value: [Integer(numerator), Integer(denominator)])
+      end
+    end
+  end
+end