mui 0.2.0 → 0.3.0

data/docs/jobs.md

@@ -0,0 +1,297 @@
+---
+title: Jobs
+layout: default
+nav_order: 6
+---
+
+# Asynchronous Jobs
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+Mui's job system allows plugins to run background tasks without blocking the editor. This is essential for:
+
+- Running tests
+- Executing linters/formatters
+- Making HTTP requests
+- Any long-running operation
+
+## Running Async Ruby Code
+
+Use `ctx.run_async` to execute Ruby code in a background thread:
+
+```ruby
+command :slow_task do |ctx|
+  ctx.set_message("Starting task...")
+
+  ctx.run_async do
+    # This runs in a background thread
+    sleep 5  # Simulate slow operation
+    "Task completed!"
+  end
+end
+```
+
+### With Callback
+
+```ruby
+command :fetch_data do |ctx|
+  ctx.run_async(on_complete: ->(result) {
+    ctx.set_message("Result: #{result}")
+  }) do
+    # Perform async work
+    fetch_from_api
+  end
+end
+```
+
+---
+
+## Running Shell Commands
+
+Use `ctx.run_shell_command` for external processes:
+
+```ruby
+command :run_tests do |ctx|
+  ctx.set_message("Running tests...")
+
+  ctx.run_shell_command("bundle exec rake test") do |result|
+    if result[:success]
+      ctx.open_scratch_buffer("[Test Results]", result[:stdout])
+      ctx.set_message("Tests passed!")
+    else
+      ctx.open_scratch_buffer("[Test Errors]", result[:stderr])
+      ctx.set_error("Tests failed!")
+    end
+  end
+end
+```
+
+### Result Object
+
+The callback receives a hash with:
+
+| Key | Description |
+|-----|-------------|
+| `:success` | Boolean indicating exit status |
+| `:stdout` | Standard output as string |
+| `:stderr` | Standard error as string |
+| `:exit_status` | Process exit code |
+
+### Example: Linter
+
+```ruby
+command :lint do |ctx|
+  file = ctx.buffer.file_path
+
+  ctx.run_shell_command("rubocop #{file}") do |result|
+    if result[:success]
+      ctx.set_message("No lint errors!")
+    else
+      ctx.open_scratch_buffer("[Lint Results]", result[:stdout])
+    end
+  end
+end
+```
+
+---
+
+## Job Management
+
+### Checking Job Status
+
+```ruby
+command :status do |ctx|
+  if ctx.jobs_running?
+    ctx.set_message("Jobs are running...")
+  else
+    ctx.set_message("No active jobs")
+  end
+end
+```
+
+### Cancelling Jobs
+
+```ruby
+command :start_job do |ctx|
+  job_id = ctx.run_async do
+    # Long running task
+    loop do
+      sleep 1
+    end
+  end
+
+  # Store job_id for later cancellation
+  @current_job = job_id
+end
+
+command :cancel_job do |ctx|
+  if @current_job
+    ctx.cancel_job(@current_job)
+    ctx.set_message("Job cancelled")
+  end
+end
+```
+
+---
+
+## Scratch Buffers
+
+Display job results in a scratch buffer:
+
+```ruby
+ctx.open_scratch_buffer(name, content)
+```
+
+- Opens in a horizontal split
+- Buffer is read-only
+- Subsequent calls with same name update existing buffer
+
+### Example: Test Runner
+
+```ruby
+command :test do |ctx|
+  ctx.run_shell_command("rake test") do |result|
+    output = []
+    output << "=== Test Results ==="
+    output << ""
+    output << result[:stdout]
+
+    if result[:stderr].length > 0
+      output << ""
+      output << "=== Errors ==="
+      output << result[:stderr]
+    end
+
+    output << ""
+    output << "Exit status: #{result[:exit_status]}"
+
+    ctx.open_scratch_buffer("[Test Output]", output.join("\n"))
+  end
+end
+```
+
+---
+
+## Job Events
+
+React to job lifecycle with autocmd:
+
+```ruby
+autocmd :JobStarted do |ctx|
+  ctx.set_message("Job started")
+end
+
+autocmd :JobCompleted do |ctx|
+  ctx.set_message("Job completed successfully")
+end
+
+autocmd :JobFailed do |ctx|
+  ctx.set_error("Job failed!")
+end
+
+autocmd :JobCancelled do |ctx|
+  ctx.set_message("Job was cancelled")
+end
+```
+
+---
+
+## Complete Example: Build Plugin
+
+```ruby
+class BuildPlugin < Mui::Plugin
+  name :build
+  version "1.0.0"
+  description "Build and test runner"
+
+  def setup
+    command :build do |ctx|
+      run_build(ctx)
+    end
+
+    command :test do |ctx|
+      run_tests(ctx)
+    end
+
+    command :check do |ctx|
+      run_build(ctx)
+      run_tests(ctx)
+    end
+
+    keymap :normal, "<Leader>b" do |ctx|
+      run_build(ctx)
+    end
+
+    keymap :normal, "<Leader>t" do |ctx|
+      run_tests(ctx)
+    end
+
+    autocmd :JobCompleted do |ctx|
+      # Could trigger notifications, update status line, etc.
+    end
+  end
+
+  private
+
+  def run_build(ctx)
+    ctx.set_message("Building...")
+
+    ctx.run_shell_command("make build") do |result|
+      if result[:success]
+        ctx.set_message("Build succeeded!")
+      else
+        ctx.open_scratch_buffer("[Build Errors]", result[:stderr])
+        ctx.set_error("Build failed!")
+      end
+    end
+  end
+
+  def run_tests(ctx)
+    ctx.set_message("Running tests...")
+
+    ctx.run_shell_command("make test") do |result|
+      ctx.open_scratch_buffer("[Test Results]", result[:stdout])
+
+      if result[:success]
+        ctx.set_message("All tests passed!")
+      else
+        ctx.set_error("Tests failed!")
+      end
+    end
+  end
+end
+```
+
+---
+
+## Interactive Commands
+
+For commands that require user interaction (like fzf), use `run_interactive_command`:
+
+```ruby
+command :find_file do |ctx|
+  unless ctx.command_exists?("fzf")
+    ctx.set_error("fzf is not installed")
+    return
+  end
+
+  # This temporarily exits curses mode
+  result = ctx.run_interactive_command("find . -type f | fzf")
+
+  if result && !result.empty?
+    ctx.editor.execute_command("e #{result.strip}")
+  end
+end
+```
+
+{: .note }
+`run_interactive_command` blocks and waits for the command to complete. Use this only for interactive CLI tools that require terminal access.

data/docs/keybindings.md

@@ -0,0 +1,229 @@
+---
+title: Key Bindings
+layout: default
+nav_order: 3
+---
+
+# Key Bindings
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Normal Mode
+
+### Cursor Movement
+
+| Key | Action |
+|-----|--------|
+| `h` | Move left |
+| `j` | Move down |
+| `k` | Move up |
+| `l` | Move right |
+| `0` | Move to line start |
+| `^` | Move to first non-blank character |
+| `$` | Move to line end |
+
+### Word Movement
+
+| Key | Action |
+|-----|--------|
+| `w` | Move to next word start |
+| `b` | Move to previous word start |
+| `e` | Move to word end |
+
+### File Movement
+
+| Key | Action |
+|-----|--------|
+| `gg` | Go to first line |
+| `G` | Go to last line |
+| `:{number}` | Go to line number |
+
+### Character Search
+
+| Key | Action |
+|-----|--------|
+| `f{char}` | Find character forward (on character) |
+| `F{char}` | Find character backward (on character) |
+| `t{char}` | Find character forward (before character) |
+| `T{char}` | Find character backward (after character) |
+
+### Search
+
+| Key | Action |
+|-----|--------|
+| `/pattern` | Search forward |
+| `?pattern` | Search backward |
+| `n` | Next match |
+| `N` | Previous match |
+| `*` | Search word under cursor (forward) |
+| `#` | Search word under cursor (backward) |
+
+### Entering Insert Mode
+
+| Key | Action |
+|-----|--------|
+| `i` | Insert before cursor |
+| `a` | Append after cursor |
+| `I` | Insert at line start |
+| `A` | Append at line end |
+| `o` | Open line below |
+| `O` | Open line above |
+
+### Operators
+
+Operators can be combined with motions (e.g., `dw` = delete word).
+
+| Key | Action |
+|-----|--------|
+| `d` | Delete |
+| `c` | Change (delete and enter Insert mode) |
+| `y` | Yank (copy) |
+
+### Common Operations
+
+| Key | Action |
+|-----|--------|
+| `dd` | Delete line |
+| `cc` | Change line |
+| `yy` | Yank line |
+| `x` | Delete character at cursor |
+| `p` | Paste after cursor |
+| `P` | Paste before cursor |
+| `u` | Undo |
+| `Ctrl-r` | Redo |
+
+### Visual Mode
+
+| Key | Action |
+|-----|--------|
+| `v` | Enter Visual mode |
+| `V` | Enter Visual Line mode |
+| `gv` | Reselect last visual selection |
+
+### Tabs and Windows
+
+| Key | Action |
+|-----|--------|
+| `gt` | Go to next tab |
+| `gT` | Go to previous tab |
+| `Ctrl-w h` | Go to left window |
+| `Ctrl-w j` | Go to below window |
+| `Ctrl-w k` | Go to above window |
+| `Ctrl-w l` | Go to right window |
+| `Ctrl-w w` | Cycle to next window |
+| `Ctrl-w c` | Close current window |
+| `Ctrl-w o` | Close all other windows |
+
+### Registers
+
+| Key | Action |
+|-----|--------|
+| `"a` - `"z` | Use named register |
+| `""` | Use unnamed register |
+| `"0` | Use yank register |
+| `"1` - `"9` | Use delete history |
+| `"_` | Use black hole register (discard) |
+
+Example: `"ayy` yanks line to register `a`, `"ap` pastes from register `a`.
+
+---
+
+## Insert Mode
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Return to Normal mode |
+| `Ctrl-n` | Next completion candidate |
+| `Ctrl-p` | Previous completion candidate |
+| `Tab` | Accept completion |
+| Arrow keys | Move cursor |
+| `Backspace` | Delete character before cursor |
+
+---
+
+## Visual Mode
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Return to Normal mode |
+| `d` | Delete selection |
+| `c` | Change selection |
+| `y` | Yank selection |
+| `>` | Indent selection |
+| `<` | Unindent selection |
+| `*` | Search for selected text (forward) |
+| `#` | Search for selected text (backward) |
+| All motion keys | Extend selection |
+
+---
+
+## Command Mode
+
+Enter with `:` from Normal mode.
+
+### File Commands
+
+| Command | Action |
+|---------|--------|
+| `:w` | Save file |
+| `:w filename` | Save as filename |
+| `:q` | Quit |
+| `:q!` | Force quit |
+| `:wq` | Save and quit |
+| `:e filename` | Open file |
+
+### Window Commands
+
+| Command | Action |
+|---------|--------|
+| `:sp [filename]` | Horizontal split |
+| `:vs [filename]` | Vertical split |
+| `:close` | Close window |
+| `:only` | Close all other windows |
+
+### Tab Commands
+
+| Command | Action |
+|---------|--------|
+| `:tabnew [filename]` | New tab |
+| `:tabclose` | Close tab |
+| `:tabnext` | Next tab |
+| `:tabprev` | Previous tab |
+| `:tabfirst` | First tab |
+| `:tablast` | Last tab |
+| `:tabmove N` | Move tab to position N |
+
+### Shell Commands
+
+| Command | Action |
+|---------|--------|
+| `:!cmd` | Run shell command |
+
+### Navigation
+
+| Command | Action |
+|---------|--------|
+| `:{number}` | Go to line number |
+
+---
+
+## Search Mode
+
+Enter with `/` or `?` from Normal mode.
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Execute search |
+| `Esc` | Cancel search |
+| `Tab` | Cycle through completion |
+| `Shift-Tab` | Cycle backward |
+| `Backspace` | Delete character |
+
+Search supports regular expressions.