charming 0.1.1 → 0.1.2

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  module Layouts
+    class ApplicationLayout < Charming::Presentation::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\np 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::Presentation::Components::Modal.new(
+          content: palette_component,
+          title: "Command palette",
+          help: "Type to filter. Enter selects. Escape closes.",
+          width: 52,
+          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/generators/templates/app/root_file.template

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "charming"
+require "zeitwerk"
+__DATABASE_REQUIRE__
+
+module __APP_CLASS__
+end
+
+loader = Zeitwerk::Loader.new
+loader.tag = "__APP_SNAKE__"
+loader.inflector.inflect("version" => "VERSION")
+loader.push_dir(File.expand_path("__APP_SNAKE__", __dir__), namespace: __APP_CLASS__)
+__MODEL_LOADER__loader.push_dir(File.expand_path("../app/state", __dir__), namespace: __APP_CLASS__)
+loader.push_dir(File.expand_path("../app/components", __dir__), namespace: __APP_CLASS__)
+loader.push_dir(File.expand_path("../app/views", __dir__), namespace: __APP_CLASS__)
+loader.push_dir(File.expand_path("../app/controllers", __dir__), namespace: __APP_CLASS__)
+loader.setup
+
+require_relative "../config/routes"

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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+__APP_CLASS__::Application.routes do
+  root "home#show"
+end

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

@@ -0,0 +1 @@
+# frozen_string_literal: true

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

@@ -0,0 +1,17 @@
+# 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_helper.template

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "__APP_SNAKE__"

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

@@ -0,0 +1,17 @@
+# 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

@@ -0,0 +1,16 @@
+# 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/version.template

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  VERSION = "0.1.0"
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  module Home
+    class ShowView < Charming::Presentation::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 p for commands, q to quit.", style: theme.muted
+      end
+    end
+  end
+end

data/lib/charming/generators/templates/component/component.rb.template

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class __COMPONENT_CLASS__ < Charming::Presentation::Component
+    def render
+      text "__RESOURCE_NAME__"
+    end
+  end
+end

data/lib/charming/generators/templates/controller/controller.rb.template

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

data/lib/charming/generators/templates/model/migration.rb.template

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Create__TABLE_CLASS__ < ActiveRecord::Migration[8.1]
+  def change
+    create_table :__TABLE_NAME__ do |t|
+__FIELD_LINES__      t.timestamps
+    end
+  end
+end

data/lib/charming/generators/templates/model/model.rb.template

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class __MODEL_CLASS__ < ApplicationRecord
+  end
+end

data/lib/charming/generators/templates/model/spec.rb.template

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "__APP_SNAKE__"
+
+RSpec.describe __APP_CLASS__::__MODEL_CLASS__ do
+  it "inherits from ApplicationRecord" do
+    expect(described_class.superclass).to eq(__APP_CLASS__::ApplicationRecord)
+  end
+end

data/lib/charming/generators/templates/screen/controller.rb.template

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class __CONTROLLER_CLASS__ < ApplicationController
+__CONTROLLER_BODY__
+  end
+end

data/lib/charming/generators/templates/screen/spec_controller.rb.template

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "__APP_SNAKE__"
+
+RSpec.describe __APP_CLASS__::__CONTROLLER_CLASS__ 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/screen/spec_state.rb.template

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "__APP_SNAKE__"
+
+RSpec.describe __APP_CLASS__::__STATE_CLASS__ do
+  describe "#title" do
+    it "has the correct default string value" do
+      instance = described_class.new
+      expect(instance.title).to eq("__TITLE__")
+    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/screen/spec_view.rb.template

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "__APP_SNAKE__"
+
+RSpec.describe __APP_CLASS__::__RESOURCE_MODULE__::ShowView do
+  describe "#render" do
+    it "renders the state title" do
+      view = described_class.new(__SCREEN_NAME__: double(title: "__TITLE__"))
+
+      expect(view.render).to eq("__TITLE__")
+    end
+  end
+end

data/lib/charming/generators/templates/screen/state.rb.template

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

data/lib/charming/generators/templates/screen/view.rb.template

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  module __RESOURCE_MODULE__
+    class ShowView < Charming::Presentation::View
+      def render
+        __SCREEN_NAME__.title
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  module __RESOURCE_MODULE__
+    class __ACTION_VIEW_CLASS__View < Charming::Presentation::View
+      def render
+        "__RESOURCE_NAME__"
+      end
+    end
+  end
+end

data/lib/charming/generators/view_generator.rb

@@ -2,7 +2,10 @@
 
 module Charming
   module Generators
+    # ViewGenerator implements `charming generate view NAME [ACTION]`. Writes a single
+    # view class file at `app/views/<name>/<action>_view.rb`. The *action* defaults to `show`.
     class ViewGenerator < AppFileGenerator
+      # *name* is the resource name. *args* may contain a single action name (defaults to "show").
       def initialize(name, args, out:, destination:, force: false)
         super
         raise Error, "Usage: charming generate view NAME [ACTION]" if args.length > 1
@@ -10,21 +13,34 @@ module Charming
         @action = args.fetch(0, "show")
       end
 
+      # Writes the view file to `app/views/<name>/<action>_view.rb`.
       def generate
-        create_file(File.join("app", "views", name.snake_name, "#{action}.tui.erb"), view)
+        create_file(File.join("app", "views", name.snake_name, "#{action}_view.rb"), view)
       end
 
       private
 
+      # The action name (e.g., "show", "edit").
       attr_reader :action
 
+      # The file-name suffix used by `app_path` (sets "view" so the file is
+      # `<name>_view.rb`). Not used directly by this generator but required by the parent.
       def suffix
         "view"
       end
 
+      # The full source of the generated view class.
       def view
-        %(<%= "#{name.class_name}" %>
-)
+        render_template("view/view.rb.template",
+          app_class: app_name.class_name,
+          resource_module: name.class_name,
+          resource_name: name.class_name,
+          action_view_class: action_class_name)
+      end
+
+      # CamelCase rendering of the action name (e.g., "user_settings" → "UserSettings").
+      def action_class_name
+        action.split("_").map(&:capitalize).join
       end
     end
   end

data/lib/charming/internal/renderer/differential.rb

@@ -3,13 +3,22 @@
 module Charming
   module Internal
     module Renderer
+      # Differential renders frame updates by emitting only the lines that changed since
+      # the previous frame. On the first frame it falls back to a full repaint; when no
+      # lines changed it returns without writing anything.
       class Differential
+        # *output* is the terminal backend (must support `write_lines` for the differential
+        # path or `write_frame` for the fallback). *full_renderer* is the FullRepaint used
+        # for the initial frame and as a fallback when *output* doesn't support partial writes.
         def initialize(output, full_renderer: FullRepaint.new(output))
           @output = output
           @full_renderer = full_renderer
           @previous_frame = nil
         end
 
+        # Renders *frame*. The first call performs a full repaint and stores the frame.
+        # Subsequent calls compute the per-line diff and emit only changed rows. Returns nil
+        # when the frame is identical to the previous one.
         def render(frame)
           frame = frame.to_s
           return render_initial(frame) unless @previous_frame
@@ -20,11 +29,15 @@ module Charming
 
         private
 
+        # Performs the initial full repaint and records the first frame.
         def render_initial(frame)
           @full_renderer.render(frame)
           @previous_frame = frame
         end
 
+        # Computes the per-line diff against the previous frame, writes the changed lines,
+        # and records the new frame. Falls back to a full repaint when the output backend
+        # doesn't support partial writes.
         def render_changes(frame)
           changes = changed_lines(@previous_frame, frame)
           return @previous_frame = frame if changes.empty?
@@ -37,6 +50,8 @@ module Charming
           @previous_frame = frame
         end
 
+        # Returns an array of [1-based-row, line] tuples covering the larger of the two
+        # frames' line counts, with empty strings padding the shorter frame.
         def changed_lines(previous_frame, frame)
           previous_lines = previous_frame.lines(chomp: true)
           lines = frame.lines(chomp: true)

data/lib/charming/internal/renderer/full_repaint.rb

@@ -3,11 +3,17 @@
 module Charming
   module Internal
     module Renderer
+      # FullRepaint clears the screen and rewrites the entire frame on every render. It is
+      # used as the initial render path by Differential and as a fallback for backends that
+      # don't support partial line writes.
       class FullRepaint
+        # *output* is the terminal backend (must support `clear`, `move_cursor`, and
+        # `write_frame` per the Adapter contract).
         def initialize(output)
           @output = output
         end
 
+        # Clears the screen, homes the cursor, and writes the entire *frame* string.
         def render(frame)
           @output.clear
           @output.move_cursor(1, 1)

data/lib/charming/internal/terminal/adapter.rb

@@ -3,46 +3,72 @@
 module Charming
   module Internal
     module Terminal
-      # Contract for terminal adapters used by Runtime and renderers.
-      # Concrete adapters provide input events, terminal dimensions, and output
-      # primitives for full or partial frame rendering.
+      # Adapter defines the duck-typed interface that terminal backends must implement.
+      # Concrete adapters (`TTYBackend`, `MemoryBackend`) mix this module in and provide
+      # the actual implementations; the methods below raise NotImplementedError to make
+      # missing implementations fail loudly.
+      #
+      # Input methods:
+      # - `read_event(timeout:)` returns the next event (KeyEvent, MouseEvent, or nil on timeout)
+      #
+      # Output methods:
+      # - `size` returns the [width, height] of the terminal
+      # - `enter_alt_screen` / `leave_alt_screen` switch to/from the alternate screen buffer
+      # - `hide_cursor` / `show_cursor` toggle the cursor
+      # - `clear` clears the screen
+      # - `move_cursor(row, column)` positions the cursor (1-based)
+      # - `write_frame(frame)` writes a full multi-line frame string
+      # - `write_lines(line_changes, frame: nil)` writes a partial frame of [row, line] changes
       module Adapter
+        # Reads the next event from the backend. Returns nil when no event is available
+        # within *timeout* seconds. Must be implemented by the including class.
         def read_event(timeout: nil)
           raise NotImplementedError, "#{self.class} must implement #read_event"
         end
 
+        # Returns the current terminal dimensions as [width, height] in cells.
         def size
           raise NotImplementedError, "#{self.class} must implement #size"
         end
 
+        # Switches the terminal into the alternate screen buffer (used to keep the host
+        # terminal scrollback untouched while a TUI app is running).
         def enter_alt_screen
           raise NotImplementedError, "#{self.class} must implement #enter_alt_screen"
         end
 
+        # Returns the terminal to the primary screen buffer (paired with `enter_alt_screen`).
         def leave_alt_screen
           raise NotImplementedError, "#{self.class} must implement #leave_alt_screen"
         end
 
+        # Hides the terminal cursor.
         def hide_cursor
           raise NotImplementedError, "#{self.class} must implement #hide_cursor"
         end
 
+        # Shows the terminal cursor.
         def show_cursor
           raise NotImplementedError, "#{self.class} must implement #show_cursor"
         end
 
+        # Clears the entire screen and homes the cursor.
         def clear
           raise NotImplementedError, "#{self.class} must implement #clear"
         end
 
+        # Moves the cursor to the given 1-based (row, column) position.
         def move_cursor(row, column)
           raise NotImplementedError, "#{self.class} must implement #move_cursor"
         end
 
+        # Writes a full multi-line frame string to the terminal in one operation.
         def write_frame(frame)
           raise NotImplementedError, "#{self.class} must implement #write_frame"
         end
 
+        # Writes a partial frame composed of [row, line] tuples. Optional *frame:* is the
+        # full frame string for backends that want to track it (e.g., the MemoryBackend).
         def write_lines(line_changes, frame: nil)
           raise NotImplementedError, "#{self.class} must implement #write_lines"
         end

data/lib/charming/internal/terminal/key_normalizer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Terminal
+      # KeyNormalizer turns raw keypress strings (from tty-reader) into normalized
+      # KeyEvent objects with a semantic key symbol and the printable character (when
+      # applicable). Handles ctrl-modifier naming, special keys (return, tab, space),
+      # and the back-tab (Shift+Tab) variant.
+      class KeyNormalizer
+        # Matches key names like "ctrl_a" → captures "a" so the modifier can be split out.
+        CTRL_KEY_PATTERN = /\Actrl_(?<key>.+)\z/
+
+        # *reader* is a TTY::Reader used to look up canonical key names from raw keypresses.
+        def initialize(reader)
+          @reader = reader
+        end
+
+        # Converts a raw *keypress* string into a KeyEvent. Returns nil when *keypress* is nil.
+        def normalize(keypress)
+          return nil unless keypress
+
+          key_name = @reader.console.keys[keypress]
+          return character_event(keypress) unless key_name
+
+          named_event(key_name)
+        end
+
+        private
+
+        # Builds a KeyEvent for a raw character keypress (no semantic name was matched).
+        def character_event(keypress)
+          Events::KeyEvent.new(key: keypress.to_sym, char: keypress)
+        end
+
+        # Builds a KeyEvent for a named key, splitting out modifiers and the printable char.
+        def named_event(key_name)
+          normalized = normalize_key_name(key_name)
+          Events::KeyEvent.new(
+            key: normalized.fetch(:key),
+            char: normalized.fetch(:char, nil),
+            ctrl: normalized.fetch(:ctrl, false),
+            alt: normalized.fetch(:alt, false),
+            shift: normalized.fetch(:shift, false)
+          )
+        end
+
+        # Splits a key name into its semantic key, printable char, and modifier flags.
+        def normalize_key_name(key_name)
+          name = key_name.to_s
+          return ctrl_key(name) if name.match?(CTRL_KEY_PATTERN)
+          return {key: :tab, shift: true} if name == "back_tab"
+
+          {key: normalized_key(name), char: printable_char(name)}
+        end
+
+        # Returns the semantic key symbol for *name* (e.g., "return" → :enter).
+        def normalized_key(name)
+          return :enter if name == "return"
+
+          name.to_sym
+        end
+
+        # Returns a key/ctrl-modifier pair for a `ctrl_*` key name.
+        def ctrl_key(name)
+          match = name.match(CTRL_KEY_PATTERN)
+          {key: match[:key].to_sym, ctrl: true}
+        end
+
+        # Returns the printable character for *name* (e.g., "space" → " "), or nil when the
+        # name has no single-character printable form.
+        def printable_char(name)
+          case name
+          when "space" then " "
+          when "enter", "return" then "\n"
+          when "tab" then "\t"
+          else
+            name if name.length == 1 && !name.match?(/[[:cntrl:]]/)
+          end
+        end
+      end
+    end
+  end
+end