charming 0.1.0 → 0.1.2

data/lib/charming/generators/screen_generator.rb

@@ -2,19 +2,24 @@
 
 module Charming
   module Generators
+    # ScreenGenerator implements `charming generate screen NAME`. Writes a complete vertical
+    # slice for a new screen: a state class, a controller with a `show` action, a view,
+    # matching spec files, and inserts a route into `config/routes.rb` and a command entry
+    # into `ApplicationController` for the command palette.
     class ScreenGenerator < AppFileGenerator
-      include AppGenerator::ScreenSpecTemplates
-
+      # *name* is the resource name. *args* is unused (raises Error when non-empty).
       def initialize(name, args, out:, destination:, force: false)
         super
         raise Error, "Usage: charming generate screen NAME" if args.any?
       end
 
+      # Writes the state, controller, view, and three spec files, then inserts a route
+      # and a command-palette entry.
       def generate
-        create_file(model_path, model)
+        create_file(state_path, state)
         create_file(controller_path, controller)
         create_file(view_path, view)
-        create_file(spec_model_path, spec_model)
+        create_file(spec_state_path, spec_state)
         create_file(spec_controller_path, spec_controller)
         create_file(spec_view_path, spec_view)
         insert_route
@@ -23,102 +28,124 @@ module Charming
 
       private
 
+      # The file-name suffix used by `app_path` ("screen" — only used by the parent class).
       def suffix
         "screen"
       end
 
-      def model_path
-        File.join("app", "models", "#{name.snake_name}_model.rb")
+      # Path to the generated state class.
+      def state_path
+        File.join("app", "state", "#{name.snake_name}_state.rb")
       end
 
+      # Path to the generated controller class.
       def controller_path
         File.join("app", "controllers", "#{name.snake_name}_controller.rb")
       end
 
+      # Path to the generated `show` view.
       def view_path
-        File.join("app", "views", "#{name.snake_name}_view.rb")
+        File.join("app", "views", name.snake_name, "show_view.rb")
       end
 
-      def spec_model_path
-        File.join("spec", "models", "#{name.snake_name}_model_spec.rb")
+      # Path to the generated state spec.
+      def spec_state_path
+        File.join("spec", "state", "#{name.snake_name}_state_spec.rb")
       end
 
+      # Path to the generated controller spec.
       def spec_controller_path
         File.join("spec", "controllers", "#{name.snake_name}_controller_spec.rb")
       end
 
+      # Path to the generated view spec.
       def spec_view_path
-        File.join("spec", "views", "#{name.snake_name}_view_spec.rb")
+        File.join("spec", "views", name.snake_name, "show_view_spec.rb")
       end
 
+      # Absolute path to the app's `config/routes.rb`.
       def route_path
         File.join(destination, "config", "routes.rb")
       end
 
+      # Absolute path to the app's `ApplicationController`.
       def application_controller_path
         File.join(destination, "app", "controllers", "application_controller.rb")
       end
 
-      def model
-        %(# frozen_string_literal: true
-
-module #{app_name.class_name}
-  class #{name.class_name}Model < ApplicationModel
-    attribute :title, :string, default: "#{name.class_name}"
-  end
-end
-)
+      # The source of the generated state class.
+      def state
+        render_template("screen/state.rb.template",
+          app_class: app_name.class_name,
+          state_class: "#{name.class_name}State",
+          title: name.class_name)
       end
 
+      # The source of the generated controller class.
       def controller
-        %(# frozen_string_literal: true
-
-module #{app_name.class_name}
-  class #{name.controller_class_name} < ApplicationController
-#{controller_body}
-  end
-end
-)
+        render_template("screen/controller.rb.template",
+          app_class: app_name.class_name,
+          controller_class: name.controller_class_name,
+          controller_body: controller_body)
       end
 
+      # The body of the controller: a `show` action and a private accessor for the state.
       def controller_body
-        %(    def show
-      render #{name.view_class_name}.new(
-        #{name.snake_name}: #{name.snake_name},
-        palette: command_palette,
-        screen: screen
-      )
-    end
-
-    private
-
-    def #{name.snake_name}
-      model(:#{name.snake_name}, #{name.class_name}Model)
-    end)
+        "    def show\n" \
+          "      render :show,\n" \
+          "        #{name.snake_name}: #{name.snake_name},\n" \
+          "        palette: command_palette\n" \
+          "    end\n" \
+          "\n" \
+          "    private\n" \
+          "\n" \
+          "    def #{name.snake_name}\n" \
+          "      state(:#{name.snake_name}, #{name.class_name}State)\n" \
+          "    end"
+      end
+
+      # The source of the generated view class.
+      def view
+        render_template("screen/view.rb.template",
+          app_class: app_name.class_name,
+          resource_module: name.class_name,
+          screen_name: name.snake_name)
       end
 
-      def view
-        %(# frozen_string_literal: true
+      # The source of the generated state spec.
+      def spec_state
+        render_template("screen/spec_state.rb.template",
+          app_snake: app_name.snake_name,
+          app_class: app_name.class_name,
+          state_class: "#{name.class_name}State",
+          title: name.class_name)
+      end
 
-module #{app_name.class_name}
-  class #{name.view_class_name} < Charming::View
-#{view_body}
-  end
-end
-)
+      # The source of the generated controller spec.
+      def spec_controller
+        render_template("screen/spec_controller.rb.template",
+          app_snake: app_name.snake_name,
+          app_class: app_name.class_name,
+          controller_class: name.controller_class_name)
       end
 
-      def view_body
-        %(    def render
-      #{name.snake_name}.title
-    end)
+      # The source of the generated view spec.
+      def spec_view
+        render_template("screen/spec_view.rb.template",
+          app_snake: app_name.snake_name,
+          app_class: app_name.class_name,
+          resource_module: name.class_name,
+          screen_name: name.snake_name,
+          title: name.class_name)
       end
 
+      # Inserts a `screen` route into `config/routes.rb`, idempotently.
       def insert_route
         route = %(  screen "/#{name.snake_name}", to: "#{name.snake_name}#show", title: "#{name.class_name}")
         insert_before_end(route_path, route, "route", "end")
       end
 
+      # Inserts a `command` block into `ApplicationController`, idempotently.
       def insert_command
         command = %(    command "#{name.class_name}" do
       navigate_to "/#{name.snake_name}"
@@ -126,6 +153,8 @@ end
         insert_before_end(application_controller_path, command, "command", "  end")
       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)
 
@@ -139,6 +168,8 @@ end
         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
@@ -146,6 +177,7 @@ end
         index
       end
 
+      # Strips the destination prefix from *path* for human-friendly status output.
       def relative_path(path)
         path.delete_prefix("#{destination}/")
       end

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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/lib/charming/generators/templates/app/README.md.template

@@ -0,0 +1,9 @@
+# __APP_NAME__
+
+A Charming terminal user interface.
+
+Run it with:
+
+```sh
+bundle exec __APP_SNAKE__
+```

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class Application < Charming::Application
+    root File.expand_path("../..", __dir__)
+
+    Charming::Presentation::UI::Theme.built_in_names.each do |theme_name|
+      theme theme_name.to_sym, built_in: theme_name
+    end
+
+    default_theme :phosphor
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class ApplicationController < Charming::Controller
+    layout Layouts::ApplicationLayout
+    focus_ring :sidebar, :content
+
+    key "p", :open_command_palette, scope: :global
+    key "q", :quit, scope: :global
+
+    command "Home" do
+      navigate_to "/"
+    end
+
+    command "Theme", :open_theme_palette
+    command "Close palette", :close_command_palette
+    command "Quit app", :quit
+  end
+end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

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

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

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "fileutils"
+
+database_path = File.expand_path("../db/development.sqlite3", __dir__)
+FileUtils.mkdir_p(File.dirname(database_path))
+
+ActiveRecord::Base.establish_connection(
+  adapter: "sqlite3",
+  database: database_path
+)

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

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "__APP_SNAKE__"
+
+Charming.run(__APP_CLASS__::Application.new)

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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "lib/__APP_SNAKE__/version"
+
+Gem::Specification.new do |spec|
+__GEMSPEC_ATTRIBUTES____GEMSPEC_DEPENDENCIES__end

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

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

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

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