charming 0.2.2 → 0.2.3

data/lib/charming/generators/templates/layout/sidebar/application_layout.rb.template

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  module Layouts
+    class ApplicationLayout < Charming::View
+      def render
+        screen_layout(background: theme.background) do
+          split(narrow? ? :vertical : :horizontal, gap: 1) do
+            pane(:sidebar, **sidebar_options, border: :rounded, padding: [1, 2], style: sidebar_style) do
+              column(app_title, navigation, shortcuts, gap: 1)
+            end
+
+            pane(:content, grow: 1, border: :rounded, padding: [1, 2], style: content_style) do
+              yield_content
+            end
+          end
+
+          overlay command_palette_modal if command_palette_modal
+        end
+      end
+
+      private
+
+      def palette_component
+        assigns.fetch(:palette, nil)
+      end
+
+      def narrow?
+        screen.narrow?(below: 72, min_height: 20)
+      end
+
+      def sidebar_options
+        narrow? ? {height: [screen.height / 3, 5].max} : {width: 22}
+      end
+
+      def sidebar_inner_width
+        narrow? ? [screen.width - 6, 20].max : 16
+      end
+
+      def app_title
+        text "__APP_NAME__", style: theme.header_accent.align(:center).width(sidebar_inner_width)
+      end
+
+      def navigation
+        column(*nav_items)
+      end
+
+      def nav_items
+        controller.sidebar_routes.each_with_index.map do |route, index|
+          text nav_item_label(route, index), style: nav_item_style(route, index)
+        end
+      end
+
+      def nav_item_label(route, index)
+        cursor = (sidebar_focused? && index == sidebar_index) ? ">" : " "
+        active = current_route?(route) ? "\u{25cf}" : " "
+        "#{cursor} #{active} #{route.title}"
+      end
+
+      def nav_item_style(route, index)
+        if sidebar_focused? && index == sidebar_index
+          theme.selected
+        elsif current_route?(route)
+          theme.title
+        else
+          theme.muted
+        end
+      end
+
+      def shortcuts
+        text "tab focus\nctrl+p commands\nq quit", style: theme.muted
+      end
+
+      def sidebar_style
+        focused_style = sidebar_focused? ? theme.title : theme.border
+        palette_component ? focused_style.faint : focused_style
+      end
+
+      def content_style
+        focused_style = content_focused? ? theme.title : theme.border
+        palette_component ? focused_style.faint : focused_style
+      end
+
+      def command_palette_modal
+        return unless palette_component
+
+        render_component Charming::Components::CommandPaletteModal.new(
+          content: palette_component,
+          theme: theme
+        )
+      end
+
+      def sidebar_focused?
+        controller.sidebar_focused?
+      end
+
+      def content_focused?
+        controller.content_focused?
+      end
+
+      def sidebar_index
+        controller.sidebar_index
+      end
+
+      def current_route?(route)
+        controller.current_route?(route)
+      end
+    end
+  end
+end

data/lib/charming/image/protocol/kitty.rb

@@ -82,6 +82,13 @@ module Charming
           end.join("\n")
         end
 
+        # Builds the `a=d,d=I` escape that deletes *image_id*'s placements AND frees its data from
+        # terminal memory (lowercase `d=i` would keep the data resident). Long-lived apps that cycle
+        # many images must emit this when evicting, or the terminal's image storage grows unbounded.
+        def delete(image_id:)
+          "\e_Ga=d,d=I,i=#{image_id},q=2\e\\"
+        end
+
         # The chunked `a=t` (transmit) escapes carrying the base64 PNG data directly (`f=100,t=d`).
         # Control keys ride only the first chunk; `m=1` flags more-to-come, `m=0` the last.
         def transmit_image(image_id, png_bytes)

data/lib/charming/image/source.rb

@@ -53,6 +53,16 @@ module Charming
         protocol.placeholder_block(image_id: image_id, rows: rows, cols: cols)
       end
 
+      # Builds the out-of-band {Transmit} that frees the image from terminal memory, or nil when
+      # graphics are unsupported. Re-arms {transmitted?} so a later render retransmits. Callers
+      # evicting an image register this the same way as {transmit}.
+      def release
+        return unless protocol
+
+        @transmitted = false
+        Transmit.new(image_id: image_id, payload: protocol.delete(image_id: image_id))
+      end
+
       # True once {mark_transmitted} has recorded that the image was sent to the terminal.
       def transmitted?
         @transmitted

data/lib/charming/presentation/components/autocomplete.rb

@@ -67,6 +67,13 @@ module Charming
         end
       end
 
+      # Forwards pasted text to the inner input and re-filters the suggestions.
+      def handle_paste(event)
+        result = @input.handle_paste(event)
+        clamp_selection if result
+        result
+      end
+
       # Renders the input row followed by the suggestion dropdown.
       def render
         [input_line, *suggestion_lines].join("\n")

data/lib/charming/presentation/components/form/field.rb

@@ -41,6 +41,11 @@ module Charming
           nil
         end
 
+        # Default paste handler returns nil (paste ignored). Text fields override.
+        def handle_paste(_event)
+          nil
+        end
+
         # Renders the field as a control line prefixed with ">" (active) or " " (inactive),
         # optionally followed by the help line and any error lines.
         def render(active: false)

data/lib/charming/presentation/components/form/input.rb

@@ -27,17 +27,27 @@ module Charming
         # Forwards key events to the underlying TextInput, syncing the value and cursor
         # back into the form state. Returns :handled when the event was consumed.
         def handle_key(event)
+          forward_to_input(:handle_key, event)
+        end
+
+        # Forwards pasted text to the underlying TextInput the same way.
+        def handle_paste(event)
+          forward_to_input(:handle_paste, event)
+        end
+
+        private
+
+        # Sends *message* to a freshly-built TextInput and, when the widget consumed
+        # the event, persists the resulting value and cursor into the form state.
+        def forward_to_input(message, event)
           text_input = input
-          result = text_input.handle_key(event)
-          return nil unless result == :handled
+          return nil unless text_input.public_send(message, event) == :handled
 
           state[:values][name] = text_input.value
           field_state[:cursor] = text_input.cursor
           :handled
         end
 
-        private
-
         # The default value for a freshly-bound field is the *value* passed at construction.
         def default_value
           @initial_value

data/lib/charming/presentation/components/form/textarea.rb

@@ -29,15 +29,12 @@ module Charming
         # Forwards key events to the underlying TextArea, syncing the value, cursor, offset,
         # and preferred column back into the form state. Returns :handled when consumed.
         def handle_key(event)
-          area = text_area
-          result = area.handle_key(event)
-          return nil unless result == :handled
+          forward_to_text_area(:handle_key, event)
+        end
 
-          state[:values][name] = area.value
-          field_state[:cursor] = area.cursor
-          field_state[:offset] = area.offset
-          field_state[:preferred_column] = area.preferred_column
-          :handled
+        # Forwards pasted text (newlines preserved) to the underlying TextArea the same way.
+        def handle_paste(event)
+          forward_to_text_area(:handle_paste, event)
         end
 
         # Renders the field with its label on the first line, body lines indented, and
@@ -50,6 +47,19 @@ module Charming
 
         private
 
+        # Sends *message* to a freshly-built TextArea and, when the widget consumed the
+        # event, persists the value, cursor, offset, and preferred column into form state.
+        def forward_to_text_area(message, event)
+          area = text_area
+          return nil unless area.public_send(message, event) == :handled
+
+          state[:values][name] = area.value
+          field_state[:cursor] = area.cursor
+          field_state[:offset] = area.offset
+          field_state[:preferred_column] = area.preferred_column
+          :handled
+        end
+
         # The default value for a freshly-bound field is the *value* passed at construction.
         def default_value
           @initial_value

data/lib/charming/presentation/components/form.rb

@@ -38,6 +38,12 @@ module Charming
         advance_or_submit if key == :enter
       end
 
+      # Forwards pasted text to the currently focused field. Text fields insert it
+      # at their cursor; other fields ignore it.
+      def handle_paste(event)
+        current_field&.handle_paste(event)
+      end
+
       # Forms accept free-typed text (their input/textarea fields do), so printable
       # characters route here before global/content key bindings.
       def captures_text?

data/lib/charming/presentation/components/modal.rb

@@ -39,8 +39,8 @@ module Charming
         result
       end
 
-      # Renders the modal as a bordered, padded string with the title and help lines stacked
-      # above the content.
+      # Renders the modal as a bordered, padded string with the title above the content
+      # and the help footer below it.
       def render
         box(column(*lines, gap: 1), style: modal_style)
       end
@@ -49,9 +49,9 @@ module Charming
 
       attr_reader :content, :title, :help, :width
 
-      # Returns the array of non-nil lines: title, help, content.
+      # Returns the array of non-nil lines: title, content, help footer.
       def lines
-        [title_line, help_line, body_content].compact
+        [title_line, body_content, help_line].compact
       end
 
       # The body: windowed through a Viewport when scrollable, otherwise rendered directly.

data/lib/charming/presentation/components/stopwatch.rb

@@ -34,7 +34,7 @@ module Charming
 
       # Adds *seconds* (default 1) when running; a no-op otherwise. Returns self.
       def tick(seconds = 1)
-        @elapsed += seconds.to_i if running?
+        @elapsed += seconds if running?
         self
       end
 

data/lib/charming/presentation/components/text_area.rb

@@ -8,7 +8,7 @@ module Charming
     # for long buffers. Vertical movement preserves a "preferred column" so left/right
     # navigation feels stable.
     class TextArea < Component
-      # The current text value, cursor byte offset, top-visible row offset, and remembered
+      # The current text value, cursor character offset, top-visible row offset, and remembered
       # column for vertical navigation, respectively.
       attr_reader :value, :cursor, :offset, :preferred_column
 
@@ -212,7 +212,7 @@ module Charming
         [row, column]
       end
 
-      # Returns the byte offset where line *row* begins in the value.
+      # Returns the character offset where line *row* begins in the value.
       def line_start(row)
         lines.first(row).sum(&:length) + row
       end

data/lib/charming/presentation/components/text_input.rb

@@ -25,7 +25,7 @@ module Charming
         delete: :delete_at_cursor
       }.freeze
 
-      # The current input string and the byte offset of the cursor within it.
+      # The current input string and the character offset of the cursor within it.
       attr_reader :value, :cursor
 
       # *value* is the initial text. *placeholder* is shown when the value is empty.
@@ -94,7 +94,7 @@ module Charming
         !char.match?(/[[:cntrl:]]/)
       end
 
-      # Inserts *char* at the cursor and advances the cursor by its byte length.
+      # Inserts *char* at the cursor and advances the cursor by its character length.
       def insert(char)
         @value = value[0...cursor] + char + value[cursor..]
         @cursor += char.length

data/lib/charming/presentation/components/timer.rb

@@ -18,7 +18,7 @@ module Charming
 
       # Counts down by *seconds* (default 1), clamping at zero. Returns self.
       def tick(seconds = 1)
-        @remaining = [@remaining - seconds.to_i, 0].max
+        @remaining = [@remaining - seconds, 0].max
         self
       end
 

data/lib/charming/presentation/components/toast.rb

@@ -3,9 +3,10 @@
 module Charming
   module Components
     # Toast is a small auto-dismissing notification panel, usually composited as an
-    # overlay anchored to a screen corner. Controllers manage its lifetime with the
-    # `show_toast` / `dismiss_toast` helpers (which pair it with a timer); the component
-    # itself just renders the styled box.
+    # overlay anchored to a screen corner. The component just renders the styled box;
+    # apps manage its lifetime themselves — typically a session-backed hash with an
+    # expiry deadline plus a controller timer that clears it (see the journal example's
+    # ApplicationController#show_toast / #expire_toast).
     #
     #   Toast.new(message: "Saved!", kind: :success)
     #

data/lib/charming/presentation/components/viewport.rb

@@ -25,7 +25,10 @@ module Charming
       # *content* may be a string, an array of lines, or any object responding to `render`.
       # *width* and *height* constrain the visible window; *offset* is the top-visible row
       # and *column* is the left-visible column. *wrap* enables soft-wrapping of long lines.
-      def initialize(content:, width: nil, height: nil, offset: 0, column: 0, wrap: false, keymap: :vim)
+      # *follow* pins the viewport to the bottom of the content regardless of *offset*, so
+      # callers that rebuild each event stick to new content; pair with `at_bottom?` to
+      # decide whether to keep following after the user scrolls.
+      def initialize(content:, width: nil, height: nil, offset: 0, column: 0, wrap: false, keymap: :vim, follow: false)
         super()
         @content = content
         @width = width
@@ -34,6 +37,7 @@ module Charming
         @wrap = wrap
         @keymap = keymap
         position.clamp(bounds)
+        position.move_to(max_offset, bounds) if follow
       end
 
       # Renders the visible window of content as a multi-line string.
@@ -51,6 +55,12 @@ module Charming
         @position.column
       end
 
+      # True when the last content row is visible. Callers persisting follow mode
+      # store this after key dispatch to decide whether the next build follows.
+      def at_bottom?
+        offset >= max_offset
+      end
+
       # Handles mouse events: scroll wheel adjusts the row offset, click moves the top
       # visible row to the clicked position. Returns :handled on success.
       def handle_mouse(event)

data/lib/charming/runtime.rb

@@ -16,7 +16,7 @@ module Charming
       @task_queue = Thread::Queue.new
       @task_executor = build_task_executor(task_executor)
       @application.task_executor = @task_executor
-      @route = @application.routes.resolve("/")
+      @route = resolve_route("/")
       @screen = backend_screen
       @coalesce_input = @application.respond_to?(:coalesce_input?) && @application.coalesce_input?
       @event_loop = build_event_loop
@@ -281,11 +281,22 @@ module Charming
     def resolve_response(response)
       return response unless response.navigate?
 
-      @route = @application.routes.resolve(response.path)
+      @route = resolve_route(response.path)
       @event_loop.reset_timers(@route.controller_class.timer_bindings.values)
       dispatch(@route.action)
     end
 
+    # Resolves *path* from the app's router. An unrouted "/" falls back to the app's
+    # first route, or to the built-in welcome screen when no routes are defined yet
+    # (like Rails' welcome page); other unrouted paths still raise.
+    def resolve_route(path)
+      @application.routes.resolve(path)
+    rescue KeyError
+      raise unless path == "/"
+
+      @application.routes.all.first || Welcome.route
+    end
+
     # Derives Screen dimensions (width, height) from the terminal backend.
     def backend_screen
       width, height = @backend.size

data/lib/charming/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Charming
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: charming
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - pando
@@ -223,6 +223,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 +240,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
@@ -381,6 +377,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