charming 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e0eaad21d88747b525afbae63f84bf610e51efe4fbc56d5e628255efe66e35d8
+  data.tar.gz: 2e4b4669da9b3975a8e09b6d248e1b74802b216f8036e52e6df8582cebc289c7
+SHA512:
+  metadata.gz: bf4004256b03622484367fa47cdcd5a855f9693f6623e1f3b54fc54c9d952f66477ad3ef6342963f1cdc0fca75eb9b0dd399ca2f9d07f217198c1f02ae139372
+  data.tar.gz: 4257cdb45bd0fa51866f4ada6db6a279cc92cec5b23248ee1d7bf467fbebc546564df83c57bd93ca797ebc81a5cee9b562a31ac93a6771483b8f2643e7452cf0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 pandorocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,421 @@
+# Charming
+
+A Rails-inspired terminal user interface framework for **Ruby 4+**.
+
+```ruby
+class MyApp < Charming::Application
+  routes do
+    root "counter#show"
+  end
+end
+
+class CounterController < Charming::Controller
+  key "up", :increment
+  key "down", :decrement
+  key "q", :quit, scope: :global
+
+  def show
+    render "Count: #{counter.count}"
+  end
+
+  def increment
+    counter.count += 1
+    show
+  end
+
+  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:
+
+```bash
+bundle install
+```
+
+## Generating an App
+
+Create a complete, runnable Charming app with the built-in generator:
+
+```bash
+charming new my_app
+cd my_app
+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`:
+
+```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
+
+Application models inherit from `Charming::ApplicationModel`, which includes `ActiveModel::Model` and `ActiveModel::Attributes`:
+
+```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
+```
+
+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
+```
+
+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
+```
+
+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.
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+bin/check            # run everything — RSpec + Standard Ruby
+```
+
+Common binstubs:
+
+```bash
+bin/rspec             # run specs only
+bin/format            # auto-format with Standard Ruby
+bin/lint              # style checks with Standard Ruby
+bin/check             # run everything
+```

data/exe/charming

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "charming"
+
+exit Charming::CLI.new.call(ARGV)

data/lib/charming/application.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Charming
+  # Application is a lightweight, Rails-inspired application base for building
+  # terminal-based apps. It provides routing (via a DSL), session storage, and
+  # task execution for managing async operations.
+  class Application
+    THEME_READER = Object.new.freeze
+
+    class << self
+      # Registers or returns the app's Router. Accepts an optional block to define
+      # routes via DSL (screen, root). Lazily initializes a new Router per namespace.
+      def routes(&block)
+        @routes ||= Router.new(namespace: namespace)
+        @routes.draw(&block) if block
+        @routes
+      end
+
+      # Derives the module namespace from the class name — e.g., Admin::HomeController
+      # yields "Admin". Mirrors Rails' engine-style namespacing.
+      def namespace
+        name&.split("::")&.then { |parts| parts[0...-1].join("::") }
+      end
+
+      def root(path = THEME_READER)
+        return @root if path == THEME_READER
+
+        @root = File.expand_path(path)
+      end
+
+      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)
+        else
+          UI::Theme.load_file(resolve_theme_path(from))
+        end
+      end
+
+      def themes
+        @themes ||= superclass.respond_to?(:themes) ? superclass.themes.dup : {}
+      end
+
+      def default_theme(name = THEME_READER)
+        return @default_theme || themes.keys.first if name == THEME_READER
+
+        @default_theme = name.to_sym
+      end
+
+      def theme_for(name = nil)
+        theme_name = name || default_theme
+        return UI::Theme.default unless theme_name
+
+        themes.fetch(theme_name.to_sym)
+      end
+
+      private
+
+      def resolve_theme_path(path)
+        return path if File.absolute_path?(path)
+
+        File.expand_path(path, root || Dir.pwd)
+      end
+    end
+
+    attr_accessor :task_executor
+    attr_reader :session
+
+    # Initializes an empty session hash for per-request state storage.
+    def initialize
+      @session = {}
+    end
+
+    # Delegates to the class-level Router, providing instance access to route definitions.
+    def routes
+      self.class.routes
+    end
+
+    def theme
+      self.class.theme_for(session[:theme])
+    end
+
+    def use_theme(name)
+      self.class.theme_for(name)
+      session[:theme] = name.to_sym
+    end
+  end
+end

data/lib/charming/application_model.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Charming
+  # ApplicationModel is the persistent state base for application data models. 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
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+  end
+end

data/lib/charming/cli.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Charming
+  class CLI
+    def initialize(out: $stdout, err: $stderr, pwd: Dir.pwd)
+      @out = out
+      @err = err
+      @pwd = pwd
+    end
+
+    def call(argv)
+      command, *args = argv
+      case command
+      when "new" then new_app(args)
+      when "generate", "g" then generate(args)
+      else usage(1)
+      end
+    rescue Generators::Error => e
+      err.puts e.message
+      1
+    end
+
+    private
+
+    attr_reader :out, :err, :pwd
+
+    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
+      0
+    end
+
+    def generate(args)
+      force = args.delete("--force")
+      type = args.shift || raise(Generators::Error, "Usage: charming generate TYPE NAME [actions]")
+      generator(type, args, force).generate
+      0
+    end
+
+    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
+
+    def generator_class(type)
+      {
+        "controller" => Generators::ControllerGenerator,
+        "screen" => Generators::ScreenGenerator,
+        "view" => Generators::ViewGenerator,
+        "component" => Generators::ComponentGenerator
+      }.fetch(type) { raise Generators::Error, "Unknown generator: #{type}" }
+    end
+
+    def usage(status)
+      err.puts "Usage: charming new NAME | charming generate TYPE NAME [actions]"
+      status
+    end
+  end
+end

data/lib/charming/component.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Charming
+  # Component is the base class for all reusable terminal widgets. It inherits from View to gain assigns,
+  # helper methods (text, box, row, column, etc.), and rendering via render.
+  class Component < View
+  end
+end