ratatui_ruby 1.0.0 → 1.0.1

data/examples/app_all_events/model/msg.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-# Semantic message types for the Model-View-Update architecture.
-#
-# Raw events from the terminal are converted to semantic Msg types. This
-# decouples the Update function from the event system, making it easier
-# to test and reason about.
-#
-# === Example
-#
-#   msg = Msg::Input.new(event: key_event)
-#   msg = Msg::Quit.new
-module Msg
-  # A keyboard, mouse, or paste event to record.
-  Input = Data.define(:event)
-
-  # A terminal resize event.
-  #
-  # [width] Integer new terminal width
-  # [height] Integer new terminal height
-  # [previous_size] Array [width, height] before resize
-  Resize = Data.define(:width, :height, :previous_size)
-
-  # A focus change event.
-  #
-  # [gained] Boolean true if focus was gained, false if lost
-  Focus = Data.define(:gained)
-
-  # A none/timeout event (no input received).
-  NoneEvent = Data.define
-
-  # A quit signal.
-  Quit = Data.define
-end

data/examples/app_all_events/model/timestamp.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-# Represents a high-resolution point in time.
-#
-# Comparing events and calculating durations requires consistent time measurement.
-# Standard Time objects are often too granular or complex for simple millisecond offsets.
-#
-# This class provides a millisecond-precision timestamp for event measurement.
-#
-# Use it to track event timing, calculate elapsed time, or trigger debouncing.
-#
-# === Examples
-#
-#   timestamp = Timestamp.now
-#   puts timestamp.milliseconds
-#
-#   if timestamp.elapsed?(300)
-#     puts "More than 300ms have passed."
-#   end
-class Timestamp < Data.define(:milliseconds)
-  # Returns a new Timestamp representing the current time.
-  #
-  # === Example
-  #
-  #   Timestamp.now #=> #<struct Timestamp milliseconds=123456789>
-  def self.now
-    new(milliseconds: (Time.now.to_f * 1000).to_i)
-  end
-
-  # Checks if a duration has passed since this timestamp.
-  #
-  # [duration_ms] Integer duration in milliseconds.
-  #
-  # === Example
-  #
-  #   timestamp = Timestamp.now
-  #   sleep(0.5)
-  #   timestamp.elapsed?(300) #=> true
-  def elapsed?(duration_ms)
-    Timestamp.now.milliseconds >= milliseconds + duration_ms
-  end
-
-  # Returns the current time in milliseconds.
-  #
-  # === Example
-  #
-  #   Timestamp.current #=> 123456789
-  def self.current
-    now.milliseconds
-  end
-end

data/examples/app_all_events/update.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "model/app_model"
-require_relative "model/msg"
-require_relative "model/event_entry"
-require_relative "model/timestamp"
-require_relative "model/event_color_cycle"
-
-# Pure update function for the Model-View-Update architecture.
-#
-# Given a Msg and the current AppModel, returns the next AppModel.
-# This function is pure: it does not mutate arguments, draw to the screen,
-# or perform IO. It simply calculates the next state.
-#
-# === Example
-#
-#   model = AppModel.initial
-#   msg = Msg::Input.new(event: key_event)
-#   new_model = Update.call(msg, model)
-module Update
-  extend self
-
-  # Processes a message and returns the next model.
-  #
-  # [msg] A Msg value object
-  # [model] The current AppModel
-  #
-  # === Example
-  #
-  #   Update.call(Msg::Quit.new, model) #=> model (unchanged)
-  def call(msg, model)
-    case msg
-    in Msg::Quit
-      model
-    in Msg::NoneEvent
-      model.with(none_count: model.none_count + 1)
-    in Msg::Focus(gained:)
-      event = gained ? RatatuiRuby::Event::FocusGained.new : RatatuiRuby::Event::FocusLost.new
-      entry = create_entry(event, model)
-      add_entry(model, entry, :focus).with(focused: gained)
-    in Msg::Resize(width:, height:, previous_size: _)
-      event = RatatuiRuby::Event::Resize.new(width:, height:)
-      entry = create_entry(event, model)
-      add_entry(model, entry, :resize).with(window_size: [width, height])
-    in Msg::Input(event:)
-      entry = create_entry(event, model)
-      add_entry(model, entry, entry.live_type)
-    else
-      model
-    end
-  end
-
-  # Creates an EventEntry with the next color and current timestamp.
-  def create_entry(event, model)
-    EventEntry.create(event, model.next_color, Timestamp.now)
-  end
-
-  # Adds an entry to the model, updates highlights, and advances the color cycle.
-  def add_entry(model, entry, live_type)
-    new_entries = model.entries + [entry]
-    new_lit_types = model.lit_types.merge(live_type => Timestamp.now)
-    new_color_index = (model.color_cycle_index + 1) % EventColorCycle::COLORS.length
-
-    model.with(
-      entries: new_entries,
-      lit_types: new_lit_types,
-      color_cycle_index: new_color_index
-    )
-  end
-end

data/examples/app_all_events/view/app_view.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "../view"
-require_relative "counts_view"
-require_relative "live_view"
-require_relative "log_view"
-require_relative "controls_view"
-
-# Orchestrates the complete UI layout and sub-view composition.
-#
-# Complex applications need a structured way to divide the screen and delegate rendering.
-# Placing all layout logic in one monolithic method makes the code difficult to maintain.
-#
-# This class defines the screen layout using a series of split constraints and delegates to sub-views.
-#
-# Use it as the root view for the All Events example application.
-#
-# === Examples
-#
-#   app_view = View::App.new
-#   app_view.call(model, tui, frame, area)
-class View::App
-  # Creates a new View::App and initializes sub-views.
-  def initialize
-    @counts_view = View::Counts.new
-    @live_view = View::Live.new
-    @log_view = View::Log.new
-    @controls_view = View::Controls.new
-  end
-
-  # Renders the entire application UI to the given area.
-  #
-  # [model] AppModel containing all application data.
-  # [tui] RatatuiRuby instance.
-  # [frame] RatatuiRuby::Frame being rendered.
-  # [area] RatatuiRuby::Layout::Rect defining the total available space.
-  #
-  # === Example
-  #
-  #   app_view.call(model, tui, frame, area)
-  def call(model, tui, frame, area)
-    main_area, control_area = tui.layout_split(
-      area,
-      direction: :vertical,
-      constraints: [
-        tui.constraint_fill(1),
-        tui.constraint_length(3),
-      ]
-    )
-
-    counts_area, _margin_area, right_area = tui.layout_split(
-      main_area,
-      direction: :horizontal,
-      constraints: [
-        tui.constraint_length(20),
-        tui.constraint_length(1),
-        tui.constraint_fill(1),
-      ]
-    )
-
-    live_area, log_area = tui.layout_split(
-      right_area,
-      direction: :vertical,
-      constraints: [
-        tui.constraint_length(9),
-        tui.constraint_fill(1),
-      ]
-    )
-
-    @counts_view.call(model, tui, frame, counts_area)
-    @live_view.call(model, tui, frame, live_area)
-    @log_view.call(model, tui, frame, log_area)
-    @controls_view.call(model, tui, frame, control_area)
-  end
-end

data/examples/app_all_events/view/controls_view.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "../view"
-
-# Renders the keyboard controls and shortcuts panel.
-#
-# Users need to know how to interact with the application and exit.
-# Hardcoding control descriptions into the main layout makes the code hard to read.
-#
-# This component renders a formatted paragraph listing available global shortcuts.
-#
-# Use it to display help information in a sidebar or dedicated panel.
-#
-# === Examples
-#
-#   controls = View::Controls.new
-#   controls.call(model, tui, frame, area)
-class View::Controls
-  # Renders the controls widget to the given area.
-  #
-  # [model] AppModel (unused, included for consistent interface).
-  # [tui] RatatuiRuby instance.
-  # [frame] RatatuiRuby::Frame being rendered.
-  # [area] RatatuiRuby::Layout::Rect defining the widget's bounds.
-  #
-  # === Example
-  #
-  #   controls.call(model, tui, frame, area)
-  def call(_model, tui, frame, area)
-    hotkey_style = tui.style(modifiers: [:bold, :underlined])
-
-    widget = tui.paragraph(
-      text: [
-        tui.text_line(spans: [
-          tui.text_span(content: "q", style: hotkey_style),
-          tui.text_span(content: ": Quit  "),
-          tui.text_span(content: "Ctrl+C", style: hotkey_style),
-          tui.text_span(content: ": Quit"),
-        ]),
-      ],
-      block: tui.block(
-        title: "Controls",
-        borders: [:all],
-        border_style: tui.style(fg: :white)
-      )
-    )
-    frame.render_widget(widget, area)
-  end
-end

data/examples/app_all_events/view/counts_view.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "../view"
-
-# Renders the event statistics dashboard.
-#
-# Developers auditing input need to see real-time counts of various event types.
-#
-# This component displays a list of event types with their total counts.
-#
-# Use it to build an interactive dashboard of application activity.
-class View::Counts
-  # Renders the event counts widget to the given area.
-  #
-  # [model] AppModel containing event data.
-  # [tui] RatatuiRuby instance.
-  # [frame] RatatuiRuby::Frame being rendered.
-  # [area] RatatuiRuby::Layout::Rect defining the widget's bounds.
-  def call(model, tui, frame, area)
-    dimmed_style = tui.style(fg: :dark_gray)
-    lit_style = tui.style(fg: :green, modifiers: [:bold])
-    border_color = model.focused ? :green : :gray
-
-    count_lines = []
-
-    AppAllEvents::EVENT_TYPES.each do |type|
-      count = model.count(type)
-      label = type.to_s.capitalize
-      style = model.lit?(type) ? lit_style : nil
-
-      count_lines << tui.text_line(spans: [
-        tui.text_span(content: "#{label}: ", style:),
-        tui.text_span(content: count.to_s, style: style || tui.style(fg: :yellow)),
-      ])
-
-      model.sub_counts(type).each do |sub_type, sub_count|
-        sub_label = sub_type.to_s.capitalize
-        count_lines << tui.text_line(spans: [
-          tui.text_span(content: "  #{sub_label}: ", style: dimmed_style),
-          tui.text_span(content: sub_count.to_s, style: dimmed_style),
-        ])
-      end
-    end
-
-    widget = tui.paragraph(
-      text: count_lines,
-      scroll: [0, 0],
-      block: tui.block(
-        title: "Event Counts",
-        borders: [:all],
-        border_style: tui.style(fg: border_color)
-      )
-    )
-    frame.render_widget(widget, area)
-  end
-end

data/examples/app_all_events/view/live_view.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "../view"
-
-# Renders a real-time summary of the most recent events.
-#
-# Users need to see the immediate result of their actions without digging through a log.
-# Identifying the specific details of the last key press or mouse move at a glance is difficult.
-#
-# This component displays a table showing the latest event of each type with its timestamp and description.
-#
-# Use it to provide instant feedback for user interactions.
-#
-# === Examples
-#
-#   live_view = View::Live.new
-#   live_view.call(model, tui, frame, area)
-class View::Live
-  # Renders the live event table to the given area.
-  #
-  # [model] AppModel containing event data.
-  # [tui] RatatuiRuby instance.
-  # [frame] RatatuiRuby::Frame being rendered.
-  # [area] RatatuiRuby::Layout::Rect defining the widget's bounds.
-  #
-  # === Example
-  #
-  #   live_view.call(model, tui, frame, area)
-  def call(model, tui, frame, area)
-    border_color = model.focused ? :green : :gray
-    rows = []
-
-    rows << tui.text_line(spans: [
-      tui.text_span(content: "Type".ljust(9), style: tui.style(fg: :gray, modifiers: [:bold])),
-      tui.text_span(content: "Time".ljust(10), style: tui.style(fg: :gray, modifiers: [:bold])),
-      tui.text_span(content: "Description", style: tui.style(fg: :gray, modifiers: [:bold])),
-    ])
-
-    (AppAllEvents::EVENT_TYPES - [:none]).each do |type|
-      event_data = model.live_event(type)
-
-      class_str = type.to_s.capitalize
-      time_str = event_data ? event_data[:time].strftime("%H:%M:%S") : "—"
-      desc_str = event_data ? event_data[:description] : "—"
-
-      is_lit = model.lit?(type)
-      row_style = is_lit ? tui.style(fg: :green, modifiers: [:reversed]) : nil
-
-      rows << tui.text_line(spans: [
-        tui.text_span(content: class_str.ljust(9), style: row_style || tui.style(fg: :cyan)),
-        tui.text_span(content: time_str.ljust(10), style: row_style || tui.style(fg: :white)),
-        tui.text_span(content: desc_str, style: row_style),
-      ])
-    end
-
-    widget = tui.paragraph(
-      text: rows,
-      scroll: [0, 0],
-      block: tui.block(
-        title: "Live Display",
-        borders: [:all],
-        border_style: tui.style(fg: border_color)
-      )
-    )
-    frame.render_widget(widget, area)
-  end
-end

data/examples/app_all_events/view/log_view.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "../view"
-
-# Renders a detailed, scrollable history of application events.
-#
-# Debugging complex event flows requires a chronological record of raw data.
-# Interpreting raw event objects without formatting is difficult and slow.
-#
-# This component renders event history as a series of formatted, color-coded entries showing raw data.
-#
-# Use it to provide a detailed audit trail of all terminal interactions.
-class View::Log
-  # Renders the event log widget to the given area.
-  #
-  # [model] AppModel containing event data.
-  # [tui] RatatuiRuby instance.
-  # [frame] RatatuiRuby::Frame being rendered.
-  # [area] RatatuiRuby::Layout::Rect defining the widget's bounds.
-  def call(model, tui, frame, area)
-    dimmed_style = tui.style(fg: :dark_gray)
-    border_color = model.focused ? :green : :gray
-
-    visible_entries_count = (area.height - 2) / 2
-    display_entries = model.visible(visible_entries_count)
-
-    log_lines = []
-    if model.empty?
-      log_lines << tui.text_line(spans: [tui.text_span(content: "No events yet...", style: dimmed_style)])
-    else
-      display_entries.each do |entry|
-        entry_style = tui.style(fg: entry.color)
-        description = entry.description
-
-        log_lines << tui.text_line(spans: [tui.text_span(content: description, style: entry_style)])
-        log_lines << tui.text_line(spans: [tui.text_span(content: "", style: entry_style)])
-      end
-    end
-
-    widget = tui.paragraph(
-      text: log_lines,
-      scroll: [0, 0],
-      wrap: { trim: true },
-      block: tui.block(
-        title: "Event Log",
-        borders: [:all],
-        border_style: tui.style(fg: border_color)
-      )
-    )
-    frame.render_widget(widget, area)
-  end
-end

data/examples/app_all_events/view.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-module View
-end

data/examples/app_cli_rich_moments/README.md

@@ -1,81 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# CLI Rich Moments Example
-
-[![CLI Rich Moments](../../doc/images/app_cli_rich_moments.gif)](app.rb)
-
-Demonstrates inline viewport usage for CLI tools that need brief moments of rich interactivity without full-screen commitment.
-
-## Context
-
-CLI applications often need moments of richness—a spinner while connecting, a quick menu selection, or a brief editor. But committing to a full-screen TUI feels wrong when 90% of the app is traditional CLI output.
-
-## Problem
-
-Standard full-screen TUIs (alternate screen) erase themselves on exit. Your carefully formatted CLI output disappears. Users lose their history. The terminal scrollback becomes useless.
-
-## Solution
-
-This example shows how **inline viewports** solve this problem. Inline regions persist in terminal scrollback after exit. You can mix inline and fullscreen viewports across multiple `RatatuiRuby.run` calls in a single application flow.
-
-## Flow
-
-The application demonstrates four distinct phases:
-
-1. **1-line inline**: Braille spinner (⠋ ⠙ ⠹ etc.) + "Connecting..." status
-2. **5-line inline**: Radio button menu with up/down/enter navigation  
-3. **Fullscreen**: Configuration editor showing legitimate use of alternate screen
-4. **1-line inline**: Braille spinner + "Saving..." confirmation
-
-After exit, all inline outputs remain visible in terminal history. The fullscreen portion disappears cleanly.
-
-## Running
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-cd examples/app_cli_rich_moments
-ruby app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Architecture
-
-Each phase is a separate `RatatuiRuby.run` block with its own viewport configuration. State (like menu selection) must be passed between phases via instance variables.
-
-**Spinner phases**:
-- Use `viewport: :inline, height: 1`
-- Animate Braille frames with short delays
-- No input handling needed
-
-**Menu phase**:
-- Uses `viewport: :inline, height: 5`  
-- Handles up/down arrow keys for selection
-- Returns selected choice for next phase
-
-**Editor phase**:
-- Uses default fullscreen viewport
-- Demonstrates when alternate screen is appropriate
-- Full 80×24 available
-
-## Key Concepts
-
-- **Viewport independence**: Each `run` block can use different viewport modes
-- **Scrollback persistence**: Inline content remains after exit
-- **State management**: Pass data between phases via instance variables
-- **Appropriate contexts**: Inline for brief moments, fullscreen for sustained interaction
-
-## Learning Outcomes
-
-After studying this example, you'll understand:
-
-- When to use inline vs fullscreen viewports
-- How to mix viewport modes in a single application
-- Why inline viewports improve CLI UX for transient interactions
-- How to manage state across multiple `run` blocks