charming 0.2.2 → 0.3.0

data/lib/charming/spring.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# ******************************************************************************
+#
+#  Copyright (c) 2008-2012 Ryan Juckett
+#  http://www.ryanjuckett.com/
+#
+#  This software is provided 'as-is', without any express or implied
+#  warranty. In no event will the authors be held liable for any damages
+#  arising from the use of this software.
+#
+#  Permission is granted to anyone to use this software for any purpose,
+#  including commercial applications, and to alter it and redistribute it
+#  freely, subject to the following restrictions:
+#
+#  1. The origin of this software must not be misrepresented; you must not
+#     claim that you wrote the original software. If you use this software
+#     in a product, an acknowledgment in the product documentation would be
+#     appreciated but is not required.
+#
+#  2. Altered source versions must be plainly marked as such, and must not be
+#     misrepresented as being the original software.
+#
+#  3. This notice may not be removed or altered from any source
+#     distribution.
+#
+# ******************************************************************************
+#
+#  Ported to Go by Charmbracelet, Inc. in 2021 (charmbracelet/harmonica, MIT).
+#  Ported to Ruby for Charming in 2026 from charmbracelet/harmonica.
+#
+#  For background on the algorithm see:
+#  https://www.ryanjuckett.com/damped-springs/
+
+module Charming
+  # Spring is a damped harmonic oscillator for physics-based animation. It
+  # precomputes motion coefficients for a fixed time step so each frame update
+  # is four multiply-adds. Instances are immutable; the caller owns position
+  # and velocity (typically as Float attributes on an ApplicationState) and
+  # feeds them back in every frame:
+  #
+  #   SPRING = Charming::Spring.new(delta_time: Charming.fps(60))
+  #   position, velocity = SPRING.update(position, velocity, target)
+  #
+  # The damping ratio shapes the motion: below 1 overshoots and oscillates,
+  # exactly 1 reaches the target as fast as possible without overshooting,
+  # above 1 approaches slower still. Angular frequency scales the speed.
+  class Spring
+    def initialize(delta_time:, angular_frequency: 6.0, damping_ratio: 0.5)
+      angular_frequency = [0.0, angular_frequency].max
+      damping_ratio = [0.0, damping_ratio].max
+      @pos_pos, @pos_vel, @vel_pos, @vel_vel =
+        coefficients(delta_time, angular_frequency, damping_ratio)
+      freeze
+    end
+
+    # Advances one frame toward *target*, returning `[new_position, new_velocity]`.
+    def update(position, velocity, target)
+      relative = position - target
+      [relative * @pos_pos + velocity * @pos_vel + target,
+        relative * @vel_pos + velocity * @vel_vel]
+    end
+
+    # True once the motion has effectively come to rest at *target* — the guard
+    # for stopping an animation timer.
+    def settled?(position, velocity, target, epsilon: 0.01)
+      (position - target).abs < epsilon && velocity.abs < epsilon
+    end
+
+    private
+
+    def coefficients(delta_time, frequency, ratio)
+      return [1.0, 0.0, 0.0, 1.0] if frequency < Float::EPSILON
+
+      if ratio > 1.0 + Float::EPSILON
+        over_damped(delta_time, frequency, ratio)
+      elsif ratio < 1.0 - Float::EPSILON
+        under_damped(delta_time, frequency, ratio)
+      else
+        critically_damped(delta_time, frequency)
+      end
+    end
+
+    def over_damped(delta_time, frequency, ratio)
+      za = -frequency * ratio
+      zb = frequency * Math.sqrt(ratio * ratio - 1.0)
+      z1 = za - zb
+      z2 = za + zb
+      e2 = Math.exp(z2 * delta_time)
+      e1_over_two_zb = Math.exp(z1 * delta_time) / (2.0 * zb)
+      e2_over_two_zb = e2 / (2.0 * zb)
+      z1e1_over_two_zb = z1 * e1_over_two_zb
+      z2e2_over_two_zb = z2 * e2_over_two_zb
+
+      [e1_over_two_zb * z2 - z2e2_over_two_zb + e2,
+        -e1_over_two_zb + e2_over_two_zb,
+        (z1e1_over_two_zb - z2e2_over_two_zb + e2) * z2,
+        -z1e1_over_two_zb + z2e2_over_two_zb]
+    end
+
+    def under_damped(delta_time, frequency, ratio)
+      omega_zeta = frequency * ratio
+      alpha = frequency * Math.sqrt(1.0 - ratio * ratio)
+      exp_term = Math.exp(-omega_zeta * delta_time)
+      exp_sin = exp_term * Math.sin(alpha * delta_time)
+      exp_cos = exp_term * Math.cos(alpha * delta_time)
+      exp_omega_zeta_sin_over_alpha = omega_zeta * exp_sin / alpha
+
+      [exp_cos + exp_omega_zeta_sin_over_alpha,
+        exp_sin / alpha,
+        -exp_sin * alpha - omega_zeta * exp_omega_zeta_sin_over_alpha,
+        exp_cos - exp_omega_zeta_sin_over_alpha]
+    end
+
+    def critically_damped(delta_time, frequency)
+      exp_term = Math.exp(-frequency * delta_time)
+      time_exp = delta_time * exp_term
+      time_exp_freq = time_exp * frequency
+
+      [time_exp_freq + exp_term,
+        time_exp,
+        -frequency * time_exp_freq,
+        -time_exp_freq + exp_term]
+    end
+  end
+end

data/lib/charming/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Charming
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/charming/welcome/controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Charming
+  module Welcome
+    # Controller for the built-in welcome screen. Renders without an app layout and
+    # binds only `q` to quit.
+    class Controller < Charming::Controller
+      key "q", :quit, scope: :global
+
+      def show
+        render_view ShowView, app_name: app_display_name
+      end
+
+      private
+
+      # The app's namespace for the welcome heading, or "Charming" for anonymous apps.
+      def app_display_name
+        name = application.class.namespace
+        name.to_s.empty? ? "Charming" : name
+      end
+    end
+  end
+end

data/lib/charming/welcome/show_view.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Charming
+  module Welcome
+    # The welcome screen body: a pastel Miami-deco skyline over the app name, tagline,
+    # Charming version, and project link, centered on the terminal.
+    class ShowView < Charming::View
+      SKYLINE_COLORS = {
+        "F" => "#f0437c", # flamingo
+        "B" => "#f9cfd8", # blush
+        "M" => "#bfe8dc", # mint
+        "C" => "#f3e6c9", # cream
+        "P" => "#fdfaf3", # plaster
+        "G" => "#1d4b44"  # palm green
+      }.freeze
+
+      # Rows of [art, color mask] pairs; each mask letter colors the glyph above it.
+      SKYLINE = [
+        ["                         ▲                         ",
+          "                         F                         "],
+        ["                         █                         ",
+          "                         F                         "],
+        ["             ▄▄▄        ▄█▄        ▄▄▄             ",
+          "             BBB        PFP        MMM             "],
+        ["             ███       ▐███▌       ███             ",
+          "             BBB       PPPPP       MMM             "],
+        ["            █▀▀▀█      ▐███▌      █▀▀▀█            ",
+          "            BBBBB      PPPPP      MMMMM            "],
+        ["  ▄█▄       █████     ▐█████▌     █████       ▄█▄  ",
+          "  GGG       BBBBB     PPPPPPP     MMMMM       GGG  "],
+        ["   █   ▄▄▄ ██▀▀▀██    ▐█████▌    ██▀▀▀██ ▄▄▄   █   ",
+          "   G   CCC BBBBBBB    PPPPPPP    MMMMMMM CCC   G   "],
+        ["   █   ███ ███████   ▐███████▌   ███████ ███   █   ",
+          "   G   CCC BBBBBBB   PPPPPPPPP   MMMMMMM CCC   G   "],
+        ["   █   ███ ███████   ▐███████▌   ███████ ███   █   ",
+          "   G   CCC BBBBBBB   PPPPPPPPP   MMMMMMM CCC   G   "],
+        ["▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁",
+          "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC"]
+      ].freeze
+      SKYLINE_WIDTH = SKYLINE.map { |art, _mask| art.length }.max
+      SKYLINE_HEIGHT = SKYLINE.length
+
+      def render
+        screen_layout(background: theme.background) do
+          pane(style: centered) do
+            welcome_content
+          end
+        end
+      end
+
+      private
+
+      def centered
+        style.align(:center).align_vertical(:middle)
+      end
+
+      def welcome_content
+        column(*blocks, gap: 1, align: :center)
+      end
+
+      def blocks
+        [skyline, heading, tagline, footer, hint].compact
+      end
+
+      def skyline
+        return unless skyline_fits?
+
+        column(*SKYLINE.map { |art, mask| paint_row(art, mask) })
+      end
+
+      # Leave room below the art for the heading, tagline, footer, and hint lines.
+      def skyline_fits?
+        layout_screen.width >= SKYLINE_WIDTH && layout_screen.height >= SKYLINE_HEIGHT + 8
+      end
+
+      def paint_row(art, mask)
+        color_runs(art, mask).map { |run, key| paint(run, key) }.join
+      end
+
+      # Groups adjacent glyphs sharing a mask letter into [run, letter] pairs.
+      def color_runs(art, mask)
+        art.chars.zip(mask.chars)
+          .chunk { |_glyph, key| key || " " }
+          .map { |key, pairs| [pairs.map(&:first).join, key] }
+      end
+
+      def paint(run, key)
+        color = SKYLINE_COLORS[key]
+        color ? style.foreground(color).render(run) : run
+      end
+
+      def heading
+        text app_name, style: theme.title
+      end
+
+      def tagline
+        text "A Rails-inspired Ruby TUI framework", style: theme.text
+      end
+
+      def footer
+        column(
+          text("Charming v#{Charming::VERSION}", style: theme.muted),
+          text("https://github.com/pandorocks/charming", style: theme.muted),
+          align: :center
+        )
+      end
+
+      def hint
+        text "Define a root route in config/routes.rb to replace this screen.", style: theme.muted
+      end
+    end
+  end
+end

data/lib/charming/welcome.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Charming
+  # Welcome is the built-in placeholder screen shown when an application defines no
+  # routes yet — the TUI equivalent of Rails' welcome page. It lives in the gem and is
+  # never copied into apps: defining any route in config/routes.rb replaces it.
+  module Welcome
+    # The fallback route the Runtime uses when the application has no routes.
+    def self.route
+      Router::Route.new(path: "/", controller_class: Controller, action: :show, title: "Welcome", params: {})
+    end
+  end
+end

data/lib/charming.rb

@@ -43,6 +43,12 @@ module Charming
     Runtime.new(application, backend: backend).run
   end
 
+  # Returns the seconds-per-frame time delta for a frame rate, for initializing
+  # physics primitives: `Charming::Spring.new(delta_time: Charming.fps(60))`.
+  def self.fps(frames_per_second)
+    1.0 / frames_per_second
+  end
+
   # Returns the normalized key symbol for an event-like object — `event.key` when the object responds
   # to it, otherwise `event.to_sym`. Lets components treat raw strings and KeyEvent objects uniformly.
   def self.key_of(event)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: charming
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - pando
@@ -206,6 +206,7 @@ files:
 - lib/charming/controller/session_state.rb
 - lib/charming/controller/sidebar_navigation.rb
 - lib/charming/controller/terminal.rb
+- lib/charming/controller/timers.rb
 - lib/charming/database/commands.rb
 - lib/charming/escape.rb
 - lib/charming/events/focus_event.rb
@@ -223,6 +224,7 @@ files:
 - lib/charming/generators/controller_generator.rb
 - lib/charming/generators/database_installer.rb
 - lib/charming/generators/error.rb
+- lib/charming/generators/layout_generator.rb
 - lib/charming/generators/migration_generator.rb
 - lib/charming/generators/migration_timestamp.rb
 - lib/charming/generators/model_generator.rb
@@ -239,21 +241,16 @@ files:
 - lib/charming/generators/templates/app/dot_rspec.template
 - lib/charming/generators/templates/app/executable.template
 - lib/charming/generators/templates/app/gemspec.template
-- lib/charming/generators/templates/app/home_controller.template
-- lib/charming/generators/templates/app/home_state.template
 - lib/charming/generators/templates/app/keep.template
 - lib/charming/generators/templates/app/layout.template
 - lib/charming/generators/templates/app/root_file.template
 - lib/charming/generators/templates/app/routes.template
 - lib/charming/generators/templates/app/seeds.template
-- lib/charming/generators/templates/app/spec_controller.template
 - lib/charming/generators/templates/app/spec_helper.template
-- lib/charming/generators/templates/app/spec_state.template
-- lib/charming/generators/templates/app/spec_view.template
 - lib/charming/generators/templates/app/version.template
-- lib/charming/generators/templates/app/view.template
 - lib/charming/generators/templates/component/component.rb.template
 - lib/charming/generators/templates/controller/controller.rb.template
+- lib/charming/generators/templates/layout/sidebar/application_layout.rb.template
 - lib/charming/generators/templates/model/migration.rb.template
 - lib/charming/generators/templates/model/model.rb.template
 - lib/charming/generators/templates/model/spec.rb.template
@@ -280,6 +277,7 @@ files:
 - lib/charming/internal/terminal/modified_key_parser.rb
 - lib/charming/internal/terminal/mouse_parser.rb
 - lib/charming/internal/terminal/tty_backend.rb
+- lib/charming/internal/timer_control.rb
 - lib/charming/presentation/component.rb
 - lib/charming/presentation/components/activity_indicator.rb
 - lib/charming/presentation/components/audio.rb
@@ -370,10 +368,12 @@ files:
 - lib/charming/presentation/ui/truncate.rb
 - lib/charming/presentation/ui/width.rb
 - lib/charming/presentation/view.rb
+- lib/charming/projectile.rb
 - lib/charming/response.rb
 - lib/charming/router.rb
 - lib/charming/runtime.rb
 - lib/charming/screen.rb
+- lib/charming/spring.rb
 - lib/charming/tasks/cancelled.rb
 - lib/charming/tasks/inline_executor.rb
 - lib/charming/tasks/progress.rb
@@ -381,6 +381,9 @@ files:
 - lib/charming/tasks/threaded_executor.rb
 - lib/charming/test_helper.rb
 - lib/charming/version.rb
+- lib/charming/welcome.rb
+- lib/charming/welcome/controller.rb
+- lib/charming/welcome/show_view.rb
 - sig/charming.rbs
 homepage: https://github.com/pandorocks/charming
 licenses:

data/lib/charming/generators/templates/app/home_controller.template

@@ -1,6 +0,0 @@
-# frozen_string_literal: true
-
-module __APP_CLASS__
-  class HomeController < ApplicationController
-__CONTROLLER_ACTIONS____CONTROLLER_HELPERS__  end
-end

data/lib/charming/generators/templates/app/home_state.template

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module __APP_CLASS__
-  class HomeState < ApplicationState
-    attribute :title, :string, default: "__APP_NAME__"
-  end
-end

data/lib/charming/generators/templates/app/spec_controller.template

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require "__APP_SNAKE__"
-
-RSpec.describe __APP_CLASS__::HomeController do
-  let(:application) { __APP_CLASS__::Application.new }
-
-  subject(:controller) { described_class.new(application: application) }
-
-  describe "#show" do
-    it "renders the view with the state" do
-      response = controller.dispatch(:show)
-
-      expect(response).to respond_to(:body)
-    end
-  end
-end

data/lib/charming/generators/templates/app/spec_state.template

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require "__APP_SNAKE__"
-
-RSpec.describe __APP_CLASS__::HomeState do
-  describe "#title" do
-    it "has the correct default string value" do
-      instance = described_class.new
-      expect(instance.title).to eq("__APP_NAME__")
-    end
-
-    it "accepts overridden title values" do
-      instance = described_class.new(title: "Alternative")
-      expect(instance.title).to eq("Alternative")
-    end
-  end
-end

data/lib/charming/generators/templates/app/spec_view.template

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-require "__APP_SNAKE__"
-
-RSpec.describe __APP_CLASS__::Home::ShowView do
-  describe "#render" do
-    it "renders the state title" do
-      view = described_class.new(
-        home: double(title: "__APP_NAME__"),
-        theme: __APP_CLASS__::Application.new.theme
-      )
-
-      expect(view.render).to include("__APP_NAME__")
-    end
-  end
-end

data/lib/charming/generators/templates/app/view.template

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module __APP_CLASS__
-  module Home
-    class ShowView < Charming::View
-      def render
-        column(title_line, help_line, gap: 1)
-      end
-
-      private
-
-      def title_line
-        text home.title, style: theme.title
-      end
-
-      def help_line
-        text "Press ctrl+p for commands, q to quit.", style: theme.muted
-      end
-    end
-  end
-end