charming 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6b9e1f0689d7ebe1c6ab12b622339c8826bc3e1f44013e8b3c3d7e6e07be98a
-  data.tar.gz: d1aecf5b432f95241693509d597ca92c39b29549e3a9209be3e49421906fe60c
+  metadata.gz: 651009e81e5bb2eb02b2df432b5e399773150691413f2519a6888160b60bd1ca
+  data.tar.gz: 8aa3bf4aebc1abab7890eec9b68791d4ed0fd354cffb982cc40f2cf4f261f70c
 SHA512:
-  metadata.gz: 3440e877894c5a6146582165c7a8dd68c9d409799f8e99b517077c753f6f29ba5905346088bb5594d1a140bae1f5ba8f861f76b2f45c11ade91f0658b0108932
-  data.tar.gz: 0cede340d3d193c12acd7441868097987174dc96e85a0c9248a18b922dd0df341ebd7f8d305ee901df703b1553a5966aab611ddde9aa3e07e8ac5db2cca52cd7
+  metadata.gz: d4276dd6ef588077877b4d4d44758a9c176161fccddd22a5d74161f8615ee38f3c8078872a0ccbca6c8d73e83c994f7e0221f45f75348b9b81bef507a35ff491
+  data.tar.gz: 595008aad5caa6c524e872593b8554b588c8018592aca1ead16820200c31dec67cb1189e338658e902abafa9033612780441ed71bb57bcdb8f296b8f03bbfecc

data/README.md

@@ -1,8 +1,10 @@
 # Charming
 
+[![CI](https://github.com/pandorocks/charming/actions/workflows/main.yml/badge.svg)](https://github.com/pandorocks/charming/actions/workflows/main.yml)
+
 A Rails-inspired terminal user interface framework for **Ruby 4+**.
 
-Charming gives terminal apps familiar application structure: routes, controllers, state objects, templates, layouts, reusable components, themes, keyboard bindings, command palettes, timers, background tasks, cross-platform audio playback, and testable terminal backends.
+Charming gives terminal apps familiar application structure: routes, controllers, state objects, templates, layouts, reusable components, themes, keyboard bindings, command palettes, timers, background tasks, cross-platform audio playback, inline image display (Kitty graphics protocol), system clipboard / desktop notifications / window title, braille charts and sparklines, and testable terminal backends.
 
 ## Project Status
 
@@ -39,7 +41,7 @@ The generator produces a Bundler gem with a Rails-like structure:
 app/controllers/                         # controller actions and input bindings
 app/state/                               # session-backed TUI state
 app/models/                              # optional Active Record models
-app/views/home/show_view.rb              # screen view classes
+app/views/                               # screen view classes
 app/views/layouts/application_layout.rb  # layout view class
 app/components/                          # reusable components
 config/routes.rb                         # route definitions
@@ -47,7 +49,17 @@ lib/my_app.rb                            # namespace loader (Zeitwerk)
 exe/my_app                               # executable entry point
 ```
 
-Generated apps include a sidebar/content layout, command palette, focus management, theme switching, and default key bindings for commands (`ctrl+p`) and quit (`q`).
+Generated apps start minimal. Until the app defines a route, it boots to a built-in welcome screen served from the gem itself (like Rails' welcome page) — generate your first screen and it disappears, with nothing to delete:
+
+```bash
+bundle exec charming generate screen home
+```
+
+Restore the full app chrome — sidebar/content layout, command palette (`ctrl+p`), focus management, and theme switching — with one command:
+
+```bash
+bundle exec charming generate layout --style sidebar
+```
 
 ## Development
 
@@ -65,4 +77,5 @@ bin/rspec             # run specs only
 bin/format            # auto-format with Standard Ruby
 bin/lint              # style checks with Standard Ruby
 bin/check             # run everything
+bin/ci                # what CI runs: specs, lint, eager-load check, gem build
 ```

data/lib/charming/application.rb

@@ -10,6 +10,7 @@ module Charming
   class Application
     LOGGER_READER = Object.new.freeze
     THEME_READER = Object.new.freeze
+    COALESCE_READER = Object.new.freeze
 
     class << self
       # Registers or returns the app's Router. Accepts an optional block to define
@@ -108,6 +109,27 @@ module Charming
         nil
       end
 
+      # When true, the runtime collapses bursts of identical key events — the flood a terminal
+      # emits while a key is held (OS auto-repeat) — into a single dispatch, so holding a key
+      # can't queue a backlog that keeps acting after release. Off by default: it also merges
+      # intentional fast repeats of the same key (e.g. tab tab), so enable it only for
+      # movement-style apps. Pass a boolean to set; call without args to read (inherited).
+      def coalesce_input(value = COALESCE_READER)
+        return configured_coalesce_input if value == COALESCE_READER
+
+        @coalesce_input = value
+      end
+
+      # The mouse motion reporting mode: :drag (default) reports movement only while
+      # a button is held; :all also reports buttonless hover movement. Pass a symbol
+      # to set; call without args to read (inherited).
+      def mouse_motion(value = COALESCE_READER)
+        return configured_mouse_motion if value == COALESCE_READER
+        raise ArgumentError, "mouse_motion must be :drag or :all" unless %i[drag all].include?(value)
+
+        @mouse_motion = value
+      end
+
       private
 
       def configured_logger
@@ -117,6 +139,20 @@ module Charming
         @logger = Logger.new(File::NULL)
       end
 
+      def configured_coalesce_input
+        return @coalesce_input if instance_variable_defined?(:@coalesce_input)
+        return superclass.coalesce_input if superclass.respond_to?(:coalesce_input)
+
+        false
+      end
+
+      def configured_mouse_motion
+        return @mouse_motion if instance_variable_defined?(:@mouse_motion)
+        return superclass.mouse_motion if superclass.respond_to?(:mouse_motion)
+
+        :drag
+      end
+
       # Expands a relative theme path against the app root (or the current working directory
       # when no root is configured). Returns *path* unchanged when it is already absolute.
       def resolve_theme_path(path)
@@ -163,6 +199,18 @@ module Charming
       session[:theme] = name.to_sym
     end
 
+    # Whether the runtime should coalesce held-key auto-repeat for this app (see the class-level
+    # `coalesce_input` DSL). Read by the Runtime at startup.
+    def coalesce_input?
+      self.class.coalesce_input == true
+    end
+
+    # The mouse motion reporting mode for this app (see the class-level `mouse_motion`
+    # DSL). Read by the Runtime at startup.
+    def mouse_motion
+      self.class.mouse_motion
+    end
+
     private
 
     # Loads the persisted session JSON (symbolizing keys), or {} when absent/invalid.

data/lib/charming/cli.rb

@@ -5,6 +5,7 @@ module Charming
   # or database commands. Subcommands:
   # - `charming new NAME [--database sqlite3] [--force]` — scaffolds a new app
   # - `charming generate TYPE NAME [args]` — runs a sub-generator (controller, model, screen, view, component)
+  # - `charming generate layout [--style sidebar]` — restores the sidebar/theme/palette app chrome
   # - `charming db:COMMAND` — runs a database command (db:create, db:migrate, db:rollback, db:drop, db:seed, db:install)
   #
   # Generator errors are caught and printed to stderr; the process exits with status 1.
@@ -58,14 +59,24 @@ module Charming
       0
     end
 
+    # Generator types that take no positional NAME argument.
+    NAMELESS_GENERATORS = %w[layout].freeze
+
     # Builds the generator instance for the given *type*, popping the name from *args*.
     def generator(type, args, force)
-      name = args.shift || raise(Generators::Error, "Usage: charming generate #{type} NAME")
-      generator_class(type).new(name, args, out: out, destination: pwd, force: force)
+      generator_class(type).new(generator_name(type, args), args, out: out, destination: pwd, force: force)
+    end
+
+    # Pops the NAME argument for a generator *type*, or supplies a fixed name for
+    # nameless generators (e.g., layout targets the application layout).
+    def generator_name(type, args)
+      return "application" if NAMELESS_GENERATORS.include?(type)
+
+      args.shift || raise(Generators::Error, "Usage: charming generate #{type} NAME")
     end
 
     # Returns the generator class for a *type* string (controller, model, screen, view,
-    # component, migration).
+    # component, migration, layout).
     def generator_class(type)
       {
         "controller" => Generators::ControllerGenerator,
@@ -73,7 +84,8 @@ module Charming
         "screen" => Generators::ScreenGenerator,
         "view" => Generators::ViewGenerator,
         "component" => Generators::ComponentGenerator,
-        "migration" => Generators::MigrationGenerator
+        "migration" => Generators::MigrationGenerator,
+        "layout" => Generators::LayoutGenerator
       }.fetch(type) { raise Generators::Error, "Unknown generator: #{type}" }
     end
 

data/lib/charming/controller/key_dispatch.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # KeyDispatch resolves which handler claims a key event — the capture/bubble
+    # ladder a browser would own in a web MVC app. Priority order:
+    #
+    # 1. Command palette (when open) consumes everything.
+    # 2. A focused text-capturing component (TextInput, TextArea, Form, …) gets
+    #    printable characters BEFORE key bindings — typing "q" into a field must
+    #    insert a q, not quit the app.
+    # 3. Global key bindings.
+    # 4. An overlay focus scope (a pushed modal) captures all remaining keys.
+    # 5. Sidebar keys (when focused), content bindings, then the focused component —
+    #    which sees Tab before ring traversal so forms can do field navigation.
+    #
+    # Tiers differ in how they terminate: the palette, overlay, sidebar, and binding
+    # tiers consume the key outright once their condition holds, while the component
+    # tiers only consume it when the component reports :handled and otherwise let it
+    # fall through to the next tier.
+    class KeyDispatch
+      def initialize(controller)
+        @controller = controller
+      end
+
+      # Runs the ladder for the controller's current event. Returns the winning
+      # tier's response, or nil when no tier claims the key.
+      def call
+        return palette_response if palette_open?
+        return response if typed_text_claimed?
+        return binding_response(global_action) if global_action
+        return overlay_response if overlay?
+        return sidebar_response if sidebar_focused?
+        return binding_response(content_action) if content_action
+        return response if component_or_ring_claimed?
+
+        nil
+      end
+
+      private
+
+      attr_reader :controller
+
+      def palette_open?
+        controller.command_palette_open?
+      end
+
+      def palette_response
+        controller.send(:dispatch_command_palette_key)
+      end
+
+      # True when a printable character was typed into a focused text-capturing
+      # component and the component consumed it.
+      def typed_text_claimed?
+        controller.send(:printable_text_event?) &&
+          controller.send(:focused_component_captures_text?) &&
+          component_claimed?
+      end
+
+      def global_action
+        controller.send(:global_key_action)
+      end
+
+      def content_action
+        controller.send(:content_key_action)
+      end
+
+      def binding_response(action)
+        controller.dispatch(action)
+      end
+
+      def overlay?
+        controller.focus.overlay?
+      end
+
+      # An overlay consumes the key whether or not the component handled it.
+      def overlay_response
+        controller.send(:dispatch_to_focused_component)
+        response
+      end
+
+      def sidebar_focused?
+        controller.sidebar_focused?
+      end
+
+      def sidebar_response
+        controller.send(:dispatch_sidebar_key)
+      end
+
+      # Text-capturing components own their remaining keys — Tab included, so forms
+      # do field navigation. Everything else keeps ring traversal ahead of the component.
+      def component_or_ring_claimed?
+        if controller.send(:focused_component_captures_text?)
+          component_claimed? || ring_claimed?
+        else
+          ring_claimed? || component_claimed?
+        end
+      end
+
+      def component_claimed?
+        controller.send(:dispatch_to_focused_component) == :handled
+      end
+
+      def ring_claimed?
+        controller.send(:dispatch_tab_traversal) == :handled
+      end
+
+      def response
+        controller.send(:response)
+      end
+    end
+  end
+end

data/lib/charming/controller/session_state.rb

@@ -30,6 +30,17 @@ module Charming
         session[:states][name.to_sym] ||= state_class.new(**attributes)
       end
 
+      # Returns the named mutable widget-state hash stored under `session[:component_state]`,
+      # seeding it from *defaults* on first access. This is the blessed way to keep an interactive
+      # component's state across ephemeral controller instances: store only JSON-safe primitives,
+      # rebuild the component from the hash each event, and write changed values back after
+      # `handle_key`. (Live component objects don't belong in the session — `save_session` drops
+      # anything that can't survive a JSON round-trip.)
+      def component_state(name, **defaults)
+        session[:component_state] ||= {}
+        session[:component_state][name.to_sym] ||= defaults
+      end
+
       # Builds a Form component scoped to the named form slot in `session[:forms]`. The block is
       # evaluated against a Form::Builder (or invoked with the builder as its argument for arity-1 blocks)
       # and returns a Form component pre-bound to the per-form mutable state hash.

data/lib/charming/controller/terminal.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Terminal mixes imperative out-of-band terminal effects into Controller: writing the system
+    # clipboard, raising desktop notifications, ringing the bell, and setting the window title. Each
+    # registers an {Charming::Escape} sequence onto the dispatch's collection; the Runtime flushes it
+    # to the backend before the next frame. They compose freely with a normal `render` — e.g.
+    # `def copy_url; copy(state.url); notify("Copied!"); render(:show); end`.
+    module Terminal
+      # Writes *text* to the system clipboard (OSC 52). *target* selects the selection (`"c"`
+      # clipboard, `"p"` primary). Works across Ghostty/Kitty/iTerm2 (and tmux with passthrough).
+      def copy(text, target: "c")
+        Escape.register(Escape.clipboard(text, target: target))
+      end
+
+      # Raises a desktop notification showing *body* (and *title* when given).
+      def notify(body, title: nil)
+        Escape.register(Escape.notification(body, title: title))
+      end
+
+      # Rings the terminal bell.
+      def bell
+        Escape.register(Escape.bell)
+      end
+
+      # Sets the terminal window/tab title to *text* (OSC 0).
+      def set_title(text)
+        Escape.register(Escape.title(text))
+      end
+    end
+  end
+end

data/lib/charming/controller.rb

@@ -17,6 +17,7 @@ module Charming
     include CommandPalette
     include ComponentDispatching
     include Dispatching
+    include Terminal
 
     attr_reader :application, :event, :params, :screen, :route
 
@@ -39,51 +40,21 @@ module Charming
       response || render("")
     end
 
-    # Key event dispatch, in priority order:
-    # 1. Command palette (when open) consumes everything.
-    # 2. A focused text-capturing component (TextInput, TextArea, Form, …) gets
-    #    printable characters BEFORE key bindings — typing "q" into a field must
-    #    insert a q, not quit the app.
-    # 3. Global key bindings.
-    # 4. An overlay focus scope (a pushed modal) captures all remaining keys.
-    # 5. Sidebar keys (when focused), content bindings, then the focused component —
-    #    which sees Tab before ring traversal so forms can do field navigation.
+    # Key event dispatch. The precedence ladder (palette → focused text capture →
+    # global bindings → overlay → sidebar/content/component) lives in KeyDispatch.
     def dispatch_key
-      return dispatch_command_palette_key if command_palette_open?
-
-      if printable_text_event? && focused_component_captures_text?
-        return response if dispatch_to_focused_component == :handled
-      end
-
-      return dispatch(global_key_action) if global_key_action
-
-      if focus.overlay?
-        dispatch_to_focused_component
-        return response
-      end
-
-      return dispatch_sidebar_key if sidebar_focused?
-      return dispatch(content_key_action) if content_key_action
-
-      # Text-capturing components (forms, editors) own their remaining keys — Tab
-      # included, so forms do field navigation. Everything else keeps ring traversal
-      # ahead of the component.
-      if focused_component_captures_text?
-        return response if dispatch_to_focused_component == :handled
-        return response if dispatch_tab_traversal == :handled
-      else
-        return response if dispatch_tab_traversal == :handled
-        return response if dispatch_to_focused_component == :handled
-      end
-      nil
+      KeyDispatch.new(self).call
     end
 
-    # Timer event dispatcher: looks up the named action in timer bindings.
+    # Timer event dispatcher: looks up the named action in timer bindings and runs it
+    # with the full hook chain. Unlike #dispatch there is no render("") fallback — a
+    # timer action that renders nothing yields a nil response, so silent ticks skip
+    # the repaint instead of blanking the screen.
     def dispatch_timer
       b = self.class.timer_bindings[event.name.to_sym]
       return nil unless b
 
-      public_send(b.action)
+      run_action_with_hooks(b.action)
       response
     end
 
@@ -100,7 +71,7 @@ module Charming
     end
 
     # Paste event dispatcher: forwards pasted text to the focused component's
-    # `handle_paste` (TextInput, TextArea, and form fields support it).
+    # `handle_paste` (TextInput, TextArea, Form text fields, and Autocomplete support it).
     def dispatch_paste
       slot = focus.current
       return nil unless slot && respond_to?(slot, true)
@@ -126,7 +97,9 @@ module Charming
       dispatch_component_mouse
     end
 
-    # Renders a body or template wrapped in the controller's layout.
+    # Renders a body or template wrapped in the controller's layout. Out-of-band escape sequences
+    # registered while rendering (e.g. image transmissions) are collected by the Runtime around the
+    # whole dispatch and attached to the response.
     def render(body = "", **assigns)
       body = view_body(default_template_name(body), **assigns) if body.is_a?(Symbol)
       @response = Response.render(render_with_layout(body))

data/lib/charming/escape.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Charming
+  # Escape is the out-of-band terminal channel: escape sequences written straight to the terminal,
+  # *before* each frame, bypassing the line-based renderer (which measures width and would shred raw
+  # control sequences). It is the shared substrate for several primitives — image transmissions
+  # ({Charming::Image::Transmit}), clipboard writes, desktop notifications, and the window title.
+  #
+  # Sequences are gathered during an event's dispatch via a thread-local collector ({collecting} /
+  # {register}) and attached to the {Response}; the {Runtime} flushes them through
+  # `backend.write_escape`. Any object that responds to `#payload` (a string) can ride the channel;
+  # the builders here return {Sequence} value objects and sanitize interpolated text so user content
+  # can't break out of the sequence.
+  module Escape
+    # A single out-of-band sequence. *payload* is the literal escape string written to the terminal.
+    Sequence = Data.define(:payload)
+
+    # Thread-local key under which the active collection bucket is stored.
+    BUCKET_KEY = :charming_escape_bucket
+
+    class << self
+      # Runs *block* with a fresh collection bucket active and returns the bucket — the {Sequence}s
+      # registered via {register} during the block. The block's own return value is ignored (capture
+      # it via a closure). Nesting is supported: an inner collection shadows the outer.
+      def collecting
+        previous = Thread.current[BUCKET_KEY]
+        bucket = []
+        Thread.current[BUCKET_KEY] = bucket
+        yield
+        bucket
+      ensure
+        Thread.current[BUCKET_KEY] = previous
+      end
+
+      # Registers *sequence* with the active collection bucket so it is flushed to the backend. A
+      # no-op (outside a collection, or when *sequence* is nil) so callers can register freely.
+      def register(sequence)
+        return sequence unless sequence
+
+        Thread.current[BUCKET_KEY]&.push(sequence)
+        sequence
+      end
+
+      # Builds an OSC 52 clipboard-write sequence setting the *target* selection (`"c"` clipboard,
+      # `"p"` primary) to *text*. The text is base64-encoded, so any bytes are safe.
+      def clipboard(text, target: "c")
+        Sequence.new(payload: "\e]52;#{target};#{[text.to_s].pack("m0")}\a")
+      end
+
+      # Builds a desktop-notification sequence: OSC 777 (`title` + `body`) when a *title* is given,
+      # else OSC 9 (body only) — the broadly supported baseline (Ghostty, iTerm2, Kitty).
+      def notification(body, title: nil)
+        payload =
+          if title
+            "\e]777;notify;#{sanitize(title)};#{sanitize(body)}\e\\"
+          else
+            "\e]9;#{sanitize(body)}\a"
+          end
+        Sequence.new(payload: payload)
+      end
+
+      # Builds a terminal-bell sequence (BEL).
+      def bell
+        Sequence.new(payload: "\a")
+      end
+
+      # Builds an OSC 0 sequence setting the terminal window (and icon) title to *text*.
+      def title(text)
+        Sequence.new(payload: "\e]0;#{sanitize(text)}\a")
+      end
+
+      private
+
+      # Strips C0 control characters (incl. ESC and BEL) so interpolated user text can't terminate
+      # or inject into the surrounding escape sequence.
+      def sanitize(text)
+        text.to_s.gsub(/[\x00-\x1f\x7f]/, "")
+      end
+    end
+  end
+end

data/lib/charming/events/mouse_event.rb

@@ -10,11 +10,12 @@ module Charming
     }.freeze
     private_constant :MOUSE_BUTTON_MAP
 
-    # MouseEvent represents a mouse input event. *button* encodes which button or action was triggered (left,
-    # right, scroll), while *x* and *y* provide the cursor position. Modifier booleans (*ctrl*, *alt*, *shift*)
-    # capture key state at the time of the event.
-    MouseEvent = Data.define(:button, :x, :y, :ctrl, :alt, :shift) do
-      def initialize(button:, x:, y:, ctrl: false, alt: false, shift: false)
+    # MouseEvent represents a mouse input event. *button* encodes which button or action was
+    # triggered (left, right, scroll), while *x* and *y* provide the cursor position. Modifier
+    # booleans (*ctrl*, *alt*, *shift*) capture key state at the time of the event. *motion*
+    # marks drag/hover movement and *release* marks an SGR button release.
+    MouseEvent = Data.define(:button, :x, :y, :ctrl, :alt, :shift, :motion, :release) do
+      def initialize(button:, x:, y:, ctrl: false, alt: false, shift: false, motion: false, release: false)
         super
       end
 
@@ -23,9 +24,9 @@ module Charming
         MOUSE_BUTTON_MAP.fetch(button, :unknown)
       end
 
-      # Returns `true` when the current event is a click (left, middle, or right button).
+      # Returns `true` for a button press (left, middle, or right) — not a release, drag, or hover.
       def click?
-        %i[left middle right].include?(button_name)
+        !motion && !release? && %i[left middle right].include?(button_name)
       end
 
       # Returns `true` when the button name maps to either direction of scroll.
@@ -33,9 +34,21 @@ module Charming
         %i[scroll_up scroll_down].include?(button_name)
       end
 
-      # Returns `true` when the current event is a mouse release action.
+      # Returns `true` for a button release: the SGR release marker, or the legacy
+      # button-3 release code on a non-motion event. (During motion, button 3
+      # means "no button held", not a release.)
       def release?
-        button_name == :release
+        release || (!motion && button_name == :release)
+      end
+
+      # Returns `true` for any mouse movement report (drag or hover).
+      def motion?
+        motion
+      end
+
+      # Returns `true` when the mouse moved with a button held down.
+      def drag?
+        motion && %i[left middle right].include?(button_name)
       end
     end
   end

data/lib/charming/generators/app_file_generator.rb

@@ -36,6 +36,35 @@ module Charming
 
         File.basename(gemspec, ".gemspec")
       end
+
+      # Inserts *content* into *path* just before the line matching *end_line*. No-ops when
+      # the content is already present. Raises Error when the file or end-line is missing.
+      def insert_before_end(path, content, label, end_line)
+        raise Error, "Missing file: #{relative_path(path)}" unless File.exist?(path)
+
+        current = File.read(path)
+        return if current.include?(content)
+
+        lines = current.lines
+        index = insertion_index(lines, path, end_line)
+        lines.insert(index, "#{content}\n")
+        File.write(path, lines.join)
+        out.puts "insert #{label} #{relative_path(path)}"
+      end
+
+      # Returns the index of the last line in *lines* that matches *end_line* (the line
+      # just before which new content will be inserted). Raises Error when not found.
+      def insertion_index(lines, path, end_line)
+        index = lines.rindex { |line| line.chomp == end_line }
+        raise Error, "Could not update #{relative_path(path)}" unless index
+
+        index
+      end
+
+      # Strips the destination prefix from *path* for human-friendly status output.
+      def relative_path(path)
+        path.delete_prefix("#{destination}/")
+      end
     end
   end
 end