charming 0.2.1 → 0.2.3

data/lib/charming/generators/app_generator.rb

@@ -13,6 +13,7 @@ module Charming
       BASE_FILE_TEMPLATES = [
         ["Gemfile", "app/Gemfile.template", false],
         ["Rakefile", "app/Rakefile.template", false],
+        [".rspec", "app/dot_rspec.template", false],
         ["README.md", "app/README.md.template", false],
         ["%<name>s.gemspec", "app/gemspec.template", false],
         ["exe/%<name>s", "app/executable.template", true],
@@ -21,16 +22,10 @@ module Charming
         ["lib/%<name>s/version.rb", "app/version.template", false],
         ["config/routes.rb", "app/routes.template", false],
         ["app/state/application_state.rb", "app/application_state.template", false],
-        ["app/state/home_state.rb", "app/home_state.template", false],
         ["app/controllers/application_controller.rb", "app/application_controller.template", false],
-        ["app/controllers/home_controller.rb", "app/home_controller.template", false],
         ["app/views/layouts/application_layout.rb", "app/layout.template", false],
-        ["app/views/home/show_view.rb", "app/view.template", false],
         ["app/components/.keep", "app/keep.template", false],
-        ["spec/spec_helper.rb", "app/spec_helper.template", false],
-        ["spec/state/home_state_spec.rb", "app/spec_state.template", false],
-        ["spec/controllers/home_controller_spec.rb", "app/spec_controller.template", false],
-        ["spec/views/home/show_view_spec.rb", "app/spec_view.template", false]
+        ["spec/spec_helper.rb", "app/spec_helper.template", false]
       ].freeze
 
       # The list of [relative-path, template-path, executable-flag] triples to render in
@@ -95,15 +90,23 @@ module Charming
           app_class: name.class_name,
           gemspec_attributes: gemspec_attributes,
           gemspec_dependencies: gemspec_dependencies,
-          controller_actions: controller_actions,
-          controller_helpers: controller_helpers,
           database_require: database_require,
           model_loader: model_loader,
           env_setup: env_setup,
-          database_spec_setup: database_spec_setup
+          database_spec_setup: database_spec_setup,
+          database_setup: database_setup
         }
       end
 
+      # README instructions for preparing the database before first run. Empty for
+      # non-database apps.
+      def database_setup
+        return "" unless database?
+
+        "Set up the database (create + load schema + seed):\n\n" \
+          "```sh\nbundle exec charming db:setup\n```\n\n"
+      end
+
       # Pins CHARMING_ENV to "test" before the app (and its database config) loads, so
       # specs hit db/test.sqlite3. Empty for non-database apps.
       def env_setup
@@ -174,21 +177,6 @@ module Charming
           "  spec.add_dependency \"sqlite3\", \"~> 2.0\""
       end
 
-      # The body of the home controller's `show` action.
-      def controller_actions
-        "\n    def show\n" \
-          "      render :show, home: home, palette: command_palette\n" \
-          "    end"
-      end
-
-      # The body of the home controller's private `home` helper, prefixed by a blank line.
-      def controller_helpers
-        "\n\n    private\n" \
-          "    def home\n" \
-          "      state(:home, HomeState)\n" \
-          "    end"
-      end
-
       # The `require_relative "../config/database"` line when the app is database-configured.
       def database_require
         database? ? "require_relative \"../config/database\"" : ""

data/lib/charming/generators/base.rb

@@ -22,6 +22,11 @@ module Charming
       # Status output stream and destination directory accessor (subclasses use these).
       attr_reader :out, :destination
 
+      # True when overwriting existing files was requested (`--force`).
+      def force?
+        @force
+      end
+
       # Writes *content* to *path* (relative to the destination), creating intermediate
       # directories as needed. Raises Generators::Error when the file already exists and
       # *force* is false. Marks the file as executable when *executable:* is true.

data/lib/charming/generators/layout_generator.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Charming
+  module Generators
+    # LayoutGenerator implements `charming generate layout [--style sidebar]`. It restores
+    # the full app chrome that `charming new` no longer ships by default: the sidebar
+    # layout, the sidebar/content focus ring, the command palette bindings, and the
+    # built-in theme registration. Safe to re-run: existing chrome is left untouched.
+    class LayoutGenerator < AppFileGenerator
+      STYLES = %w[sidebar].freeze
+      USAGE = "Usage: charming generate layout [--style sidebar]"
+
+      # *name* is unused (the CLI passes "application"); *args* may carry `--style STYLE`.
+      def initialize(name, args, out:, destination:, force: false)
+        @style = extract_style(args)
+        super
+        raise Error, USAGE if args.any?
+      end
+
+      # Writes the styled application layout, then inserts the controller chrome and the
+      # theme registration into the existing app files.
+      def generate
+        write_layout
+        insert_controller_chrome
+        insert_theme_registration
+      end
+
+      private
+
+      # The layout style name (currently always "sidebar").
+      attr_reader :style
+
+      # The file-name suffix used by `app_path` (only used by the parent class).
+      def suffix
+        "layout"
+      end
+
+      # Extracts the optional `--style` argument from *args*, removing it in place.
+      # Defaults to the first supported style when absent.
+      def extract_style(args)
+        inline = args.find { |arg| arg.start_with?("--style=") }
+        return validate_style(args.delete(inline).split("=", 2).last) if inline
+
+        index = args.index("--style")
+        return STYLES.first unless index
+
+        args.delete_at(index)
+        validate_style(args.delete_at(index) || raise(Error, USAGE))
+      end
+
+      # Validates that *style* is a supported layout style.
+      def validate_style(style)
+        return style if STYLES.include?(style)
+
+        raise Error, "Unknown layout style: #{style.inspect} (available: #{STYLES.join(", ")})"
+      end
+
+      # Replaces the application layout with the styled one. Creates it when missing,
+      # no-ops when already styled, and refuses to clobber local edits unless forced.
+      def write_layout
+        return create_file(layout_relative_path, styled_layout) unless File.exist?(layout_path)
+        return out.puts("identical #{layout_relative_path}") if current_layout == styled_layout
+        raise Error, "#{layout_relative_path} has local changes; re-run with --force to overwrite" unless replaceable_layout?
+
+        overwrite_layout
+      end
+
+      # True when the current layout may be replaced: forced, or still the generated bare layout.
+      def replaceable_layout?
+        force? || current_layout == bare_layout
+      end
+
+      def overwrite_layout
+        File.write(layout_path, styled_layout)
+        out.puts "overwrite #{layout_relative_path}"
+      end
+
+      def current_layout
+        File.read(layout_path)
+      end
+
+      # The rendered layout for the requested style.
+      def styled_layout
+        @styled_layout ||= render_template("layout/#{style}/application_layout.rb.template",
+          app_class: app_name.class_name,
+          app_name: app_name.class_name)
+      end
+
+      # The bare layout `charming new` generates, used to recognize unmodified apps.
+      def bare_layout
+        render_template("app/layout.template", app_class: app_name.class_name)
+      end
+
+      # Inserts the focus ring, palette key binding, and palette commands into
+      # `ApplicationController`, idempotently.
+      def insert_controller_chrome
+        insert_before_end(application_controller_path, controller_chrome, "chrome", "  end")
+      end
+
+      def controller_chrome
+        class_body_block(<<~RUBY)
+          focus_ring :sidebar, :content
+
+          key "ctrl+p", :open_command_palette, scope: :global
+
+          command "Home" do
+            navigate_to "/"
+          end
+
+          command "Theme", :open_theme_palette
+          command "Close palette", :close_command_palette
+          command "Quit app", :quit
+        RUBY
+      end
+
+      # Inserts the built-in theme registration into the app's Application class, idempotently.
+      def insert_theme_registration
+        insert_before_end(application_config_path, theme_registration, "themes", "  end")
+      end
+
+      def theme_registration
+        class_body_block(<<~RUBY)
+          Charming::UI::Theme.built_in_names.each do |theme_name|
+            theme theme_name.to_sym, built_in: theme_name
+          end
+
+          default_theme :phosphor
+        RUBY
+      end
+
+      # Indents *source* to class-body depth and prefixes a blank separator line, so the
+      # inserted block reads naturally after the existing declarations.
+      def class_body_block(source)
+        body = source.gsub(/^/, "    ").gsub(/^ +$/, "").chomp
+        "\n#{body}"
+      end
+
+      def layout_relative_path
+        File.join("app", "views", "layouts", "application_layout.rb")
+      end
+
+      def layout_path
+        File.join(destination, layout_relative_path)
+      end
+
+      def application_controller_path
+        File.join(destination, "app", "controllers", "application_controller.rb")
+      end
+
+      def application_config_path
+        File.join(destination, "lib", app_name.snake_name, "application.rb")
+      end
+    end
+  end
+end

data/lib/charming/generators/screen_generator.rb

@@ -152,35 +152,6 @@ module Charming
     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)
-
-        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

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

@@ -3,3 +3,9 @@
 source "https://rubygems.org"
 
 gemspec
+
+group :development, :test do
+  gem "irb"     # `charming console` (not a default gem on Ruby 4.0+)
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.13"
+end

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

@@ -2,8 +2,22 @@
 
 A Charming terminal user interface.
 
-Run it with:
+__DATABASE_SETUP__Run it with:
 
 ```sh
 bundle exec __APP_SNAKE__
 ```
+
+Until a route is defined the app boots to Charming's built-in welcome screen. Generate
+your first screen (and make it home with `root` in `config/routes.rb`):
+
+```sh
+bundle exec charming generate screen home
+```
+
+Add the sidebar layout, command palette (`ctrl+p`), and theme switching (screens generated
+with `charming generate screen` are reached through the command palette):
+
+```sh
+bundle exec charming generate layout --style sidebar
+```

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

@@ -3,11 +3,5 @@
 module __APP_CLASS__
   class Application < Charming::Application
     root File.expand_path("../..", __dir__)
-
-    Charming::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

@@ -3,17 +3,7 @@
 module __APP_CLASS__
   class ApplicationController < Charming::Controller
     layout Layouts::ApplicationLayout
-    focus_ring :sidebar, :content
 
-    key "ctrl+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/dot_rspec.template

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

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

@@ -5,105 +5,16 @@ module __APP_CLASS__
     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
+          pane(style: centered) do
+            yield_content
           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)
+      def centered
+        style.align(:center).align_vertical(:middle)
       end
     end
   end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 __APP_CLASS__::Application.routes do
-  root "home#show"
+  # Generate your first screen with `charming generate screen NAME`, then make it home:
+  #
+  #   root "home#show"
 end

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