charming 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0eaad21d88747b525afbae63f84bf610e51efe4fbc56d5e628255efe66e35d8
-  data.tar.gz: 2e4b4669da9b3975a8e09b6d248e1b74802b216f8036e52e6df8582cebc289c7
+  metadata.gz: 2bc5c3942786d07631d42361391e76f4f42275cc472c8ff7e37669880263b978
+  data.tar.gz: b6dc9eef28cf8eb6849a9ae34a4af8e6902a0e263529762cce9a3e591ed06396
 SHA512:
-  metadata.gz: bf4004256b03622484367fa47cdcd5a855f9693f6623e1f3b54fc54c9d952f66477ad3ef6342963f1cdc0fca75eb9b0dd399ca2f9d07f217198c1f02ae139372
-  data.tar.gz: 4257cdb45bd0fa51866f4ada6db6a279cc92cec5b23248ee1d7bf467fbebc546564df83c57bd93ca797ebc81a5cee9b562a31ac93a6771483b8f2643e7452cf0
+  metadata.gz: e772a624b0f4a51d722ed40863bfae85161ac9bc1b508d7accb6cc7a4fc8f30352a79b66a9d42416992d38477c145f5ecc55c953b77aca1cf787a03a5f2f0e64
+  data.tar.gz: 61dc03c8e8ade6e62fbc86c6f76e382063cc13aa1f60cc8afa161f6a646d1e4836483f9ca9a2e8446881f5b5a65d4b8e5107e39300c5844034dbbcb33f37a47f

data/README.md

@@ -2,405 +2,65 @@
 
 A Rails-inspired terminal user interface framework for **Ruby 4+**.
 
-```ruby
-class MyApp < Charming::Application
-  routes do
-    root "counter#show"
-  end
-end
+Charming gives terminal apps familiar application structure: routes, controllers, state objects, templates, layouts, reusable components, themes, keyboard bindings, command palettes, timers, background tasks, and testable terminal backends.
 
-class CounterController < Charming::Controller
-  key "up", :increment
-  key "down", :decrement
-  key "q", :quit, scope: :global
+## Project Status
 
-  def show
-    render "Count: #{counter.count}"
-  end
+Charming is still in its infancy and is under constant development. APIs, behavior, and generated app structure may change until the project reaches a stable `1.0` release.
 
-  def increment
-    counter.count += 1
-    show
-  end
+## Quick Start
 
-  def decrement
-    counter.count -= 1
-    show
-  end
-
-  private
-
-  def counter
-    model(:counter, CounterModel)
-  end
-end
-
-class CounterModel < Charming::ApplicationModel
-  attribute :count, :integer, default: 0
-end
-```
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem "charming"
-```
-
-Then execute:
+Install the Charming CLI gem on your machine:
 
 ```bash
-bundle install
+gem install charming
 ```
 
-## Generating an App
-
-Create a complete, runnable Charming app with the built-in generator:
+Generate and run an app:
 
 ```bash
 charming new my_app
 cd my_app
+bundle install
 bundle exec exe/my_app
 ```
 
-The generator produces a full Bundler gem with conventional Rails-like structure:
-
-```text
-app/controllers/          # application controllers
-app/models/               # persistent state models
-app/views/                # screen views
-app/components/           # reusable widgets (AppFrame, etc.)
-config/routes.rb          # route definitions
-lib/my_app.rb             # namespace loader (Zeitwerk)
-exe/my_app                # executable entry point
-```
-
-Inside a generated app, scaffold more code:
-
-```bash
-charming generate controller users index show
-charming generate view details
-charming generate component status_badge
-charming g controller products        # shortcut
-```
-
-Generated apps ship with a command palette (press `p`) and a sidebar navigation layout with theming and focus management baked in.
-
-## Running Without the Generator
-
-You can also build an app from scratch. Run it with:
-
-```ruby
-Charming.run(MyApp.new)
-#        ^ entry point — starts the terminal event loop
-```
-
-The `Charming::Runtime` manages the terminal lifecycle, reads events from a TTY backend, and dispatches them to controllers. An in-memory backend (`MemoryBackend`) is available for scripting and testing without a real terminal.
-
-## Application & Routing
-
-Define routes with `root` and `screen` — each maps a URL path to a controller and action:
-
-```ruby
-class MyApp < Charming::Application
-  routes do
-    root "home#index"
-    screen "/cities/:id", to: "cities#show"
-  end
-end
-```
-
-Dynamic segments (`:id`) are available in controllers through `params`:
+Charming can also be added to an existing Ruby project with Bundler, but the primary workflow is installing the gem globally and using `charming new` to create a complete app.
 
-```ruby
-class CitiesController < Charming::Controller
-  def show
-    render "City #{params[:id]}"
-  end
-end
-```
-
-Exact routes take precedence over dynamic routes. Multiple screens are listed in route order and rendered as sidebar entries (handled automatically by generated app layouts).
-
-## Controllers
-
-The base `Charming::Controller` provides key bindings, command palette entries, timer-driven actions, navigation, and state management:
-
-**Key bindings** — strings or symbols mapped to action methods, scoped as either content-focused or global:
-
-```ruby
-class HomeController < Charming::Controller
-  key "up", :increment
-  key "j", :navigate_down, scope: :content
-  key "q", :quit, scope: :global
-end
-```
-
-**Command palette** — entries visible in the fuzzy-search command palette. Accepts a method name or an inline block:
-
-```ruby
-command "Save changes", :save
-command "Clear" do
-  @model = reset_model
-end
-```
-
-**Timers** — periodic actions that fire at a given interval on the current controller:
-
-```ruby
-timer :blink, every: 0.5, action: :toggle_spinner
-```
-
-**Model storage** — models are stored in session and lazily instantiated:
-
-```ruby
-def counter
-  model(:counter, CounterModel)
-end
-#        ^ name    ^ class
-```
-
-Subsequent calls with the same name return the cached instance. Use this pattern to define accessors on your controllers.
-
-**Navigation** — redirect to a new route or quit the application:
-
-```ruby
-navigate_to "/settings"         # redirect
-quit                             # exit the app
-open_command_palette             # open command palette
-close_command_palette            # close it
-use_theme :phosphor              # switch theme (persists in session)
-```
-
-## Models
+## Documentation
 
-Application models inherit from `Charming::ApplicationModel`, which includes `ActiveModel::Model` and `ActiveModel::Attributes`:
+| Guide | Purpose |
+|-------|---------|
+| [Docs Index](docs/README.md) | Suggested reading paths and all documentation links. |
+| [Getting Started](docs/getting_started.md) | Build and run a generated Charming app. |
+| [Core Concepts](docs/core_concepts.md) | App architecture, runtime flow, ephemeral controllers, and state. |
+| [Routing](docs/routing.md) | `root`, `screen`, dynamic params, route titles, and route order. |
+| [Controllers & Templates](docs/controllers_and_templates.md) | Actions, `render :show`, `render_template`, key bindings, commands, timers, and tasks. |
+| [Layouts](docs/layouts.md) | Template layouts, `yield_content`, split panes, overlays, responsive layouts, and styles. |
+| [State](docs/state.md) | `ApplicationState`, typed attributes, validations, and session-backed state. |
+| [Database](docs/database.md) | Optional SQLite persistence with Active Record models and migrations. |
+| [Components](docs/components.md) | Built-in components, custom components, and interaction return values. |
+| [Themes](docs/themes.md) | Theme registration, tokens, and runtime theme switching. |
+| [API Reference](docs/api.md) | Compact public API reference. |
+| [Testing](docs/testing.md) | Controller, template, component, runtime, timer, and task tests. |
 
-```ruby
-class CounterModel < Charming::ApplicationModel
-  attribute :count, :integer, default: 0
-
-  validate :count_gte_zero do
-    errors.add(:count, "must be >= 0") if count < 0
-  end
-end
-```
+## Generated App Structure
 
-Models are the only place persistent state should live. Controllers are created fresh per event — never store state on them.
-
-## Views
-
-Views inherit from `Charming::View` and expose assigns (from `initialize`) as instance-local accessor methods:
-
-```ruby
-class HomeView < Charming::View
-  def render
-    row(title, subtitle, gap: 2)
-  end
-
-  private
-
-  def title
-    text "Hello!", style: theme.title
-  end
-
-  def subtitle
-    text "World", style: theme.muted
-  end
-end
-```
+The generator produces a Bundler gem with a Rails-like structure:
 
-Views use `row`, `column` for layout, `box` for bordered containers, and `text` for styled output. Assigns passed to `initialize` become reader methods automatically:
-
-```ruby
-class HomeView < Charming::View
-  # Pass assigns via initialize; they are accessible as regular methods inside render()
-end
-
-view = HomeView.new(title: "Hello", count: 42)
-# view.title → "Hello"
-# view.count → 42
-```
-
-Defining your own method with the same name will override the auto-generated accessor.
-
-### Layouts
-
-Layouts are views that wrap the current screen with a wrapper (sidebar, header, etc.):
-
-```ruby
-class ApplicationController < Charming::Controller
-  layout Layouts::Application
-end
-```
-
-Subclasses inherit their parent's layout. Override with `layout false` to disable wrapping.
-
-Layouts use `yield_content` to render the primary screen and receive `screen`, `controller`, and `theme` as assigns:
-
-```ruby
-module MyProject
-  module Layouts
-    class Application < Charming::View
-      def render
-        body = Charming::UI.place(content, width: screen.width, height: screen.height)
-        return body unless command_palette_open?
-
-        Charming::UI.overlay(body, command_palette.render)
-      end
-    end
-  end
-end
-```
-
-### Partials
-
-Render class-based partial views from other views:
-
-```ruby
-render_component HeaderView.new(title: "Dashboard")
-#        ^ component is a View subclass or Component
-```
-
-Components are just `Charming::View` subclasses — they gain the same assigns, helpers, and rendering behavior.
-
-## Themes
-
-Applications register named themes from bundled JSON files or custom locations:
-
-```ruby
-class MyApp < Charming::Application
-  Charming::UI::Theme.built_in_names.each do |theme_name|
-    theme theme_name.to_sym, built_in: theme_name
-  end
-
-  default_theme :phosphor
-
-  theme :custom, from: "config/themes/custom.json"
-end
-```
-
-Charming ships with the Phosphor theme by default. Views use semantic tokens — not hardcoded colors — for all styling:
-
-```ruby
-text "Welcome", style: theme.title      # bright cyan + bold
-text "Status",  style: theme.muted     # dim gray
-text "Alert",   style: theme.info      # cyan
-```
-
-## Components
-
-Charming ships with interactive terminal widgets that inherit from `Charming::View` (and thus gain all View helpers):
-
-| Component | Description |
-|-----------|-------------|
-| `TextInput` | Editable text field with cursor movement, selection, and character insertion |
-| `List` | Selectable list with keyboard navigation (up/down/home/end/enter) and mouse support |
-| `Modal` | Overlay dialog with title, content, and help text |
-| `CommandPalette` | Fuzzy-search command input used internally by the framework |
-| `Viewport` | Scrollable container for tall content lists |
-| `Spinner` | Animated progress indicator |
-| `ActivityIndicator` | Spinner variant (same underlying widget) |
-| `Progressbar` | A text-based progress bar |
-| `Table` | Unicode-rendered data table with keyboard navigation and mouse selection |
-| `KeyboardHandler` | Key-mapping mixin for custom components |
-
-All components accept a `theme:` parameter and are rendered from views via `render_component`:
-
-```ruby
-render_component List.new(
-  items: ["Alpha", "Beta", "Gamma"],
-  selected_index: 0,
-  theme: theme
-)
-```
-
-Components return specific values from their `handle_key(event)` methods — the framework recognizes conventions like `[:selected, item]` and `:cancelled`. They also provide a `handle_mouse(event)` method for mouse-driven interaction.
-
-## Async Tasks
-
-Dispatch background work via `run_task` on controllers. Results arrive as `TaskEvent`s that trigger controller actions:
-
-```ruby
-class HomeController < Charming::Controller
-  on_task :fetch_data, action: :data_loaded
-
-  def load_data
-    run_task :fetch_data do
-      # runs in a background thread
-      sleep 2
-      "done"
-    end
-  end
-
-  def data_loaded
-    render "Task complete!"
-  end
-end
-```
-
-Register handlers with `on_task` on the controller and dispatch work with `run_task`.
-
-## Focus Management
-
-Multi-screen layouts can define focusable areas using `focus_ring`:
-
-```ruby
-class ApplicationController < Charming::Controller
-  focus_ring :sidebar, :content
-end
-```
-
-This enables keyboard-driven focus traversal — `Tab` cycles forward, `Shift+Tab` backward. Use `focused?(slot)`, `focus_sidebar`, and `focus_content` to programmatically control focus:
-
-```ruby
-def show
-  focus_sidebar if params[:sidebar]
-  render HomeView.new(...)
-end
-```
-
-## Layout Primitives
-
-The `Charming::UI` module provides layout primitives for building custom screen layouts. These work independently of the runtime and backends:
-
-| Method | Description |
-|--------|-------------|
-| `Style.new` | Create a new style for chaining colors, padding, borders, alignment |
-| `UI.join_horizontal(*blocks, gap: 0)` | Place blocks side-by-side |
-| `UI.join_vertical(*blocks, gap: 0)` | Stack blocks vertically |
-| `UI.center(block, width:, height:)` | Center a block in a fixed canvas |
-| `UI.place(block, width:, height:, top:, left:, background:)` | Place anywhere on a canvas |
-| `UI.overlay(base, overlay, top:, left:)` | Overlay content atop another |
-
-All methods work with ANSI-styled strings and correctly handle Unicode display widths:
-
-```ruby
-body = UI.join_horizontal(sidebar, main_content, gap: 1)
-canvas = UI.place(body, width: screen.width, height: screen.height)
-Charming::UI.overlay(canvas, modal_view.render)
-```
-
-## Testing
-
-Charming uses an in-memory backend (`MemoryBackend`) for testing, so specs run without a real terminal. Pass `backend: MemoryBackend.new(...)` to `Charming::Runtime`:
-
-```ruby
-backend = Charming::Internal::Terminal::MemoryBackend.new(
-  events: [
-    Charming::KeyEvent.new(key: :up),
-    Charming::KeyEvent.new(key: :q)
-  ]
-)
-runtime = described_class.new(app, backend: backend)
-runtime.run
-
-expect(backend.frames).to eq(["Count: 0", "Count: 1"])
-#                            ^ captured terminal output, one frame per render
+```text
+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/layouts/application_layout.rb  # layout view class
+app/components/                          # reusable components
+config/routes.rb                         # route definitions
+lib/my_app.rb                            # namespace loader (Zeitwerk)
+exe/my_app                               # executable entry point
 ```
 
-The `MemoryBackend` constructor accepts `events:` (a series of events to feed the loop), and `width:` / `height:` for screen dimensions. After running, assertions go against `backend.frames` — an array capturing each rendered terminal frame passed through `write_frame`. This pattern is used throughout the test suite.
+Generated apps include a sidebar/content layout, command palette, focus management, theme switching, and default key bindings for commands (`p`) and quit (`q`).
 
 ## Development
 
@@ -408,7 +68,7 @@ After checking out the repo, run:
 
 ```bash
 bundle install
-bin/check            # run everything — RSpec + Standard Ruby
+bin/check
 ```
 
 Common binstubs:

data/lib/charming/application.rb

@@ -22,42 +22,53 @@ module Charming
         name&.split("::")&.then { |parts| parts[0...-1].join("::") }
       end
 
+      # Returns the app's filesystem root, used to resolve relative theme and template paths.
+      # Pass *path* to set it; without arguments it returns the current value (or nil if unset).
       def root(path = THEME_READER)
         return @root if path == THEME_READER
 
         @root = File.expand_path(path)
       end
 
+      # Registers a named theme. Provide either *from:* (path to a JSON file relative to the app root)
+      # or *built_in:* (name of a bundled theme such as "phosphor"). Raises when neither or both are given.
       def theme(name, from: nil, built_in: nil)
         raise ArgumentError, "theme expects from: or built_in:" unless from || built_in
         raise ArgumentError, "theme expects either from: or built_in:, not both" if from && built_in
 
         themes[name.to_sym] = if built_in
-          UI::Theme.load_builtin(built_in)
+          Presentation::UI::Theme.load_builtin(built_in)
         else
-          UI::Theme.load_file(resolve_theme_path(from))
+          Presentation::UI::Theme.load_file(resolve_theme_path(from))
         end
       end
 
+      # Hash of all registered themes keyed by symbol, including those inherited from superclasses.
       def themes
         @themes ||= superclass.respond_to?(:themes) ? superclass.themes.dup : {}
       end
 
+      # Returns the default theme name, or sets it when *name* is given. When unset, falls back
+      # to the first registered theme. Used by `theme_for` when no name is provided.
       def default_theme(name = THEME_READER)
         return @default_theme || themes.keys.first if name == THEME_READER
 
         @default_theme = name.to_sym
       end
 
+      # Resolves a theme by *name* (or the default theme when *name* is nil). Returns the default
+      # built-in theme if no name is given and no default is registered.
       def theme_for(name = nil)
         theme_name = name || default_theme
-        return UI::Theme.default unless theme_name
+        return Presentation::UI::Theme.default unless theme_name
 
         themes.fetch(theme_name.to_sym)
       end
 
       private
 
+      # 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)
         return path if File.absolute_path?(path)
 

data/lib/charming/{application_model.rb → application_state.rb}

@@ -3,10 +3,10 @@
 require "active_model"
 
 module Charming
-  # ApplicationModel is the persistent state base for application data models. It includes
+  # ApplicationState is the base for session-backed TUI state. It includes
   # `ActiveModel::Model` (validation, initialisation) and `ActiveModel::Attributes` (typed attributes
-  # with defaults via `attribute :name, :type, default: ...`), making it suitable as session-stored root objects.
-  class ApplicationModel
+  # with defaults via `attribute :name, :type, default: ...`), making it suitable for screen/form state.
+  class ApplicationState
     include ActiveModel::Model
     include ActiveModel::Attributes
   end

data/lib/charming/cli.rb

@@ -1,18 +1,29 @@
 # frozen_string_literal: true
 
 module Charming
+  # CLI dispatches the `charming` executable's subcommands to the appropriate generators
+  # 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 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.
   class CLI
+    # *out* defaults to `$stdout`, *err* to `$stderr`, *pwd* to `Dir.pwd` (overridable for tests).
     def initialize(out: $stdout, err: $stderr, pwd: Dir.pwd)
       @out = out
       @err = err
       @pwd = pwd
     end
 
+    # Runs the CLI with the given *argv* array. Returns 0 on success, 1 on a generator error,
+    # or the status from `usage` for unknown subcommands.
     def call(argv)
       command, *args = argv
       case command
       when "new" then new_app(args)
       when "generate", "g" then generate(args)
+      when /^db:/ then database(command, args)
       else usage(1)
       end
     rescue Generators::Error => e
@@ -22,15 +33,23 @@ module Charming
 
     private
 
+    # Standard output, standard error, and working directory used for generator destinations.
     attr_reader :out, :err, :pwd
 
+    # Handles `charming new`. Validates args, extracts `--database=` and `--force`,
+    # and runs AppGenerator. Returns 0 on success, raises Generators::Error on bad input.
     def new_app(args)
       force = args.delete("--force")
-      name = args.fetch(0) { raise Generators::Error, "Usage: charming new NAME [--force]" }
-      Generators::AppGenerator.new(name, out: out, destination: pwd, force: force).generate
+      database = extract_database(args)
+      name = args.fetch(0) { raise Generators::Error, "Usage: charming new NAME [--database sqlite3] [--force]" }
+      raise Generators::Error, "Usage: charming new NAME [--database sqlite3] [--force]" if args.length > 1
+
+      Generators::AppGenerator.new(name, out: out, destination: pwd, force: force, database: database).generate
       0
     end
 
+    # Handles `charming generate TYPE NAME [args]`. Extracts `--force` and dispatches to
+    # the generator class for the requested type.
     def generate(args)
       force = args.delete("--force")
       type = args.shift || raise(Generators::Error, "Usage: charming generate TYPE NAME [actions]")
@@ -38,22 +57,62 @@ module Charming
       0
     end
 
+    # 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)
     end
 
+    # Returns the generator class for a *type* string (controller, model, screen, view, component).
     def generator_class(type)
       {
         "controller" => Generators::ControllerGenerator,
+        "model" => Generators::ModelGenerator,
         "screen" => Generators::ScreenGenerator,
         "view" => Generators::ViewGenerator,
         "component" => Generators::ComponentGenerator
       }.fetch(type) { raise Generators::Error, "Unknown generator: #{type}" }
     end
 
+    # Routes `db:*` commands to either the install path (db:install) or the generic
+    # DatabaseCommands dispatcher.
+    def database(command, args)
+      if command == "db:install"
+        database = args.shift || raise(Generators::Error, "Usage: charming db:install sqlite3")
+        raise Generators::Error, "Usage: charming db:install sqlite3" if args.any?
+
+        DatabaseInstaller.new(database, out: out, destination: pwd).install
+      else
+        raise Generators::Error, "Usage: charming #{command}" if args.any?
+
+        DatabaseCommands.new(command, out: out, destination: pwd).run
+      end
+      0
+    end
+
+    # Extracts the optional `--database=<value>` argument from *args*, removing it in place.
+    # Returns the validated database name (currently only "sqlite3") or nil when not given.
+    def extract_database(args)
+      inline = args.find { |arg| arg.start_with?("--database=") }
+      return validate_database(args.delete(inline).split("=", 2).last) if inline
+
+      index = args.index("--database")
+      return nil unless index
+
+      args.delete_at(index)
+      validate_database(args.delete_at(index) || raise(Generators::Error, "Usage: charming new NAME [--database sqlite3] [--force]"))
+    end
+
+    # Validates that *database* is a supported adapter name. Currently only "sqlite3".
+    def validate_database(database)
+      return database if database == "sqlite3"
+
+      raise Generators::Error, "Unsupported database: #{database.inspect}"
+    end
+
+    # Prints a usage banner to stderr and returns *status* (1 for unknown commands).
     def usage(status)
-      err.puts "Usage: charming new NAME | charming generate TYPE NAME [actions]"
+      err.puts "Usage: charming new NAME | charming generate TYPE NAME [args] | charming db:COMMAND"
       status
     end
   end