charming 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71b370eac77c67126921d7347a0d23f834f23774626c111445e9abdef73555d9
-  data.tar.gz: c8dd983f46183c2fbdb22f9c30753b4f1443d8de2989a4e7f90016f397aa12e4
+  metadata.gz: 651009e81e5bb2eb02b2df432b5e399773150691413f2519a6888160b60bd1ca
+  data.tar.gz: 8aa3bf4aebc1abab7890eec9b68791d4ed0fd354cffb982cc40f2cf4f261f70c
 SHA512:
-  metadata.gz: 2ee80f1c214001c8f91b36ba308f0e2f67aecbc258e7ff3ce63de2eb04093a405a0a23c3174cac6c3a1c6a98746b5353e66dd8179aebab4fe60ad35132603f19
-  data.tar.gz: 5242fbc9ad41ca1c0dbebbb070bb33cbdd1279955f81aa2f067954a1b11ffdd1b9cb7b90321285fa17e795c31d3fff32c7e052e95dee7e7c90318e19d252fba1
+  metadata.gz: d4276dd6ef588077877b4d4d44758a9c176161fccddd22a5d74161f8615ee38f3c8078872a0ccbca6c8d73e83c994f7e0221f45f75348b9b81bef507a35ff491
+  data.tar.gz: 595008aad5caa6c524e872593b8554b588c8018592aca1ead16820200c31dec67cb1189e338658e902abafa9033612780441ed71bb57bcdb8f296b8f03bbfecc

data/README.md

@@ -1,5 +1,7 @@
 # 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, inline image display (Kitty graphics protocol), system clipboard / desktop notifications / window title, braille charts and sparklines, and testable terminal backends.
@@ -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/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.rb

@@ -71,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)

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

data/lib/charming/generators/app_generator.rb

@@ -22,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
@@ -96,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
@@ -175,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\n" \
-          "    def home\n" \
-          "      state(:home, HomeState)\n" \
-          "    end\n"
-      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/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/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