thaum 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 887cd877416743a99c037ed2da42612f1f4d6343516dacf56aef1d85b45cd36f
-  data.tar.gz: ca949330c9cfc15e625e59703e9dfb42448debd8991509ac98c4993cbef5361f
+  metadata.gz: edf87796b15b377e1fb9630d63a89c488c3ef127afe5f86b00748ffe40ea6bc2
+  data.tar.gz: 4a3b2b5883f17d2a3050dc9ca0e07802c722757b4f27516ea92b73eafea53b44
 SHA512:
-  metadata.gz: 43df40cb0447321b87854589d9e813ac7b87037c648b6a345ba0d1232a33586b092007db22c8400bdbd3fe540557fb2419ae124e89fb4952707c266c5548a1dd
-  data.tar.gz: 4b899c569dae2b3f447eb98516da64c3d32efffe6166c9013d695fd5d9d2ae25811c92669b28928ed0fba968f882ebc276674d5d827fc3abc4aa072f7a7ebbfb
+  metadata.gz: cd4dac7b5e97854e8347f382101690d15216450e64de3626ac561629a763811ce6557ece95968f41cf6dfc3bd3c44357df68592dfaf16f83d3fa9b88596824c2
+  data.tar.gz: d7855d4542eb89480e215f8dd42acd9c15e444db41a9fe83acc7f1cb9f6b0d4baa02803352454767f4ce3fa8f6894063a6f29f5395db031e750d069497dbe34e

data/README.md

@@ -1,39 +1,131 @@
-# Thaum
+```
+╭─────────────────────────────────────────────────────╮
+│  ▒▒▒▒▒▒▒▒╗ ▒▒╗  ▒▒╗  ▒▒▒▒▒╗  ▒▒╗   ▒▒╗ ▒▒▒╗   ▒▒▒╗  │ 
+│  ╚══▒▒╔══╝ ▒▒║  ▒▒║ ▒▒╔══▒▒╗ ▒▒║   ▒▒║ ▒▒▒▒╗ ▒▒▒▒║  │
+│     ▒▒║    ▒▒▒▒▒▒▒║ ▒▒▒▒▒▒▒║ ▒▒║   ▒▒║ ▒▒╔▒▒▒▒╔▒▒║  │
+│     ▒▒║    ▒▒╔══▒▒║ ▒▒╔══▒▒║ ▒▒║   ▒▒║ ▒▒║╚▒▒╔╝▒▒║  │
+│     ▒▒║    ▒▒║  ▒▒║ ▒▒║  ▒▒║ ╚▒▒▒▒▒▒╔╝ ▒▒║ ╚═╝ ▒▒║  │
+│     ╚═╝    ╚═╝  ╚═╝ ╚═╝  ╚═╝  ╚═════╝  ╚═╝     ╚═╝  │ 
+╰─────────────────────────────────────────────────────╯
+```
+> A Thaum is the basic unit of magical strength. It has been universally established as the amount of magic needed to create one small white pigeon or three normal-sized billiard balls. [*](#Footnotes)
+>
+> — Terry Pratchett
 
-TODO: Delete this and the text below, and describe your gem
+Compose full-screen TUI apps from a few parts:
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/thaum`. To experiment with that code, run `bin/console` for an interactive prompt.
+- **App** — top-level container that owns layout, focus, and event handling
+- **Layout** — vertical/horizontal split DSL (`region(height: 3)`, `region(width: :fill)`, …)
+- **Sigil** — focusable, renderable leaf component (`Text`, `TextInput`, `Select`, `Button`, `ScrollView`, `Table`, `Spinner`, `ProgressBar`, `Checkbox`, `Tabs`)
+- **Octagram** — composite that contains sigils and presents itself as a distributable component
 
-## Installation
+Features:
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+- Buffer-diffing renderer with synchronized output (`\e[?2026h`)
+- Truecolor with automatic degradation to 256 / 16 / no-color based on `$COLORTERM` and `$TERM`
+- Themes (8 built-in palettes — Solarized, Gruvbox, Catppuccin, …)
+- Event dispatch: keys, paste, ticks, resize, suspend/resume
+- Focus with Tab/Shift-Tab cycling and overridable `focus_order`
+- Background work via `Thaum::Action` (concurrent-ruby thread pool)
+- Box-drawing junction merging — adjacent borders resolve to the correct corner/tee glyph automatically, across light/heavy/double weights
+- Snapshot testing via `thaum/minitest`
 
-Install the gem and add to the application's Gemfile by executing:
+## Installation
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add thaum
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install thaum
 ```
 
+Requires Ruby 3.2 or newer.
+
 ## Usage
 
-TODO: Write usage instructions here
+The `Hello World` example:
+
+```ruby
+require "thaum"
+
+class HelloWorldApp
+  include Thaum::App
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def initialize
+    @greeting = Thaum::Text.new(content: "Hello World!", align: :center)
+  end
+
+  def partition
+    vertical do
+      region(height: :fill) { @greeting }
+    end
+  end
+end
+
+Thaum.run(HelloWorldApp.new)
+
+```
+
+## Examples
+
+The `examples/` directory has a runnable demo for every shipped sigil plus a few composed apps:
+
+```bash
+bundle exec ruby examples/counter.rb         # minimal app
+bundle exec ruby examples/picker.rb          # filter-as-you-type list selector
+bundle exec ruby examples/todo.rb            # TextInput + Select + Button
+bundle exec ruby examples/stopwatch.rb       # on_tick driven
+bundle exec ruby examples/theme_picker.rb    # cycle the built-in themes
+bundle exec ruby examples/layout_demo.rb     # nested Layout DSL + border junctions
+bundle exec ruby examples/octagram_picker.rb # picker packaged as an Octagram
+```
+
+Per-sigil demos: `text.rb`, `select.rb`, `checkbox.rb`, `tabs.rb`, `spinner.rb`, `progress_bar.rb`, `scroll_view.rb`, `table.rb`.
+
+## Snapshot testing
+
+```ruby
+require "thaum/minitest"
+
+class MySigilTest < Minitest::Test
+  def test_renders_greeting
+    buffer = Thaum::Rendering::Buffer.new(width: 20, height: 3)
+    canvas = Thaum::Rendering::Canvas.new(buffer: buffer, rect: Thaum::Rect.new(x: 0, y: 0, width: 20, height: 3))
+    MySigil.new.render(canvas: canvas, theme: Thaum::Themes::DEFAULT)
+    assert_snapshot(buffer, "my_sigil/greeting")
+  end
+end
+```
+
+First run writes `test/snapshots/my_sigil/greeting.txt` (or `.ans` if the output contains ANSI styling) and passes with a warning. Re-run with `UPDATE_SNAPSHOTS=1` to refresh existing snapshots.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```bash
+bin/setup       # bundle install
+rake test       # run the test suite (Minitest)
+rake rubocop    # lint
+rake            # both
+bin/console     # IRB with thaum required
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install locally: `bundle exec rake install`. To cut a release: bump `lib/thaum/version.rb`, then `bundle exec rake release`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/thaum.
+Bug reports and pull requests are welcome at https://github.com/urug/thaum.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT. See [LICENSE.txt](LICENSE.txt).
+
+### Footnotes
+
+\* Also, a terminal window

data/examples/checkbox.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/checkbox.rb
+#
+# Demonstrates Thaum::Checkbox. Four checkboxes (one indeterminate),
+# Tab between them, Space or Enter to toggle. A status line shows the
+# current state. Press esc to quit.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+class Status
+  include Thaum::Sigil
+
+  def initialize(boxes)
+    @boxes = boxes
+  end
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    summary = @boxes.map { |b| state(b) }.join("  ")
+    canvas.text(content: " #{summary}", fg: theme.dim)
+  end
+
+  private
+
+  def state(box)
+    mark = if box.indeterminate?
+             "-"
+           else
+             box.checked? ? "✓" : " "
+           end
+    "[#{mark}] #{box.instance_variable_get(:@label)}"
+  end
+end
+
+class Hint
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    canvas.text(content: " tab next   space/enter toggles   esc quits", fg: theme.dim)
+  end
+end
+
+class CheckboxApp
+  include Thaum::App
+
+  def initialize
+    @ssl      = Thaum::Checkbox.new(label: "Enable SSL", checked: true)
+    @notify   = Thaum::Checkbox.new(label: "Email me updates")
+    @beta     = Thaum::Checkbox.new(label: "Beta features", indeterminate: true)
+    @newsletter = Thaum::Checkbox.new(label: "Newsletter (twice a month)")
+    @status   = Status.new([@ssl, @notify, @beta, @newsletter])
+    @hint     = Hint.new
+  end
+
+  def theme = Thaum::Themes::CATPPUCCIN_MOCHA
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  # Checkbox::ChangedEvent bubbles up on every toggle. The Status sigil reads
+  # each Checkbox's state at render time, so we don't need to do anything
+  # — but acknowledging the event keeps stderr clean.
+  def on_event(event)
+    return if event.is_a?(Thaum::Checkbox::ChangedEvent)
+
+    super
+  end
+
+  def partition
+    vertical do
+      region(height: 1) { @ssl }
+      region(height: 1) { @notify }
+      region(height: 1) { @beta }
+      region(height: 1) { @newsletter }
+      region(height: :fill) { @status }
+      region(height: 1) { @hint }
+    end
+  end
+end
+
+Thaum.run(CheckboxApp.new)

data/examples/counter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/counter.rb
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+class CounterSigil
+  include Thaum::Sigil
+
+  def initialize
+    @count = 0
+  end
+
+  def on_key(event)
+    case event.key
+    when :up   then @count += 1
+    when :down then @count -= 1
+    else emit(event) # Pass unhandled events up to the app
+    end
+  end
+
+  def render(canvas:, theme:)
+    y = canvas.height / 2
+
+    canvas.fill(bg: theme.bg)
+    canvas.text(content: "Count: #{@count}", fg: theme.fg, align: :center, y: y)
+    canvas.text(content: "↑ / ↓ to change  escape to quit", fg: theme.dim, align: :center, y: y + 2)
+  end
+end
+
+class CounterApp
+  include Thaum::App
+
+  def initialize
+    @counter = CounterSigil.new
+  end
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def partition
+    vertical do
+      region(height: :fill) { @counter }
+    end
+  end
+end
+
+Thaum.run(CounterApp.new)

data/examples/hello_world.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/hello_world.rb
+# A minimal "Hello World" app. Press esc to quit.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "thaum"
+
+class HelloWorldApp
+  include Thaum::App
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def initialize
+    @greeting = Thaum::Text.new(content: "Hello World!", align: :center)
+  end
+
+  def partition
+    vertical do
+      region(height: :fill) { @greeting }
+    end
+  end
+end
+
+Thaum.run(HelloWorldApp.new)

data/examples/layout_demo.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/layout_demo.rb
+#
+# Two demos in one screen:
+#
+# 1. OUTER LAYOUT — the App.partition uses several region settings:
+#      vertical with fixed heights (h: 3, h: 1) + a fill row
+#      horizontal with mixed (w: 12, w: :fill, w: "20%", min: 18)
+#      header row split with (w: "30%", w: :fill, w: 10)
+#    Each region holds a flat-color HeaderItem so you can see what
+#    Layout placed where.
+#
+# 2. INNER GRID — a single Grid sigil fills the center cell and draws
+#    multiple bordered panels on overlapping rects. The cells where
+#    panels meet are shared, and Buffer#set merges box-drawing glyphs,
+#    so all the internal junctions resolve to ┬ ├ ┤ ┴ ┼ automatically.
+#
+# Press esc to quit.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+class HeaderItem
+  include Thaum::Sigil
+
+  def initialize(label:, color:)
+    @label = label
+    @color = color
+  end
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: @color)
+    y = [canvas.height / 2, 0].max
+    canvas.text(content: @label, align: :center, y: y, fg: theme.bg, bg: @color)
+  end
+end
+
+class Grid
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  # All panels are described relative to the grid's own (0,0). Adjacent
+  # rects share their edge column or row by one cell so Buffer#set's
+  # merge produces a junction instead of two parallel lines.
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    panels = panel_panels(w: canvas.width, h: canvas.height)
+    panels.each { |pair| border(canvas: canvas, rect: pair.first, theme: theme) }
+    panels.each { |pair| label(canvas: canvas, rect: pair.first, label: pair.last, theme: theme) } # rubocop:disable Style/CombinableLoops
+  end
+
+  private
+
+  def panel_panels(w:, h:)
+    th, mh, my, by, bh = band_offsets(h)
+    half = (w / 2.0).ceil + 1 # +1 so the two middle cells share a column
+    [
+      [panel(x: 0,        y: 0,  ww: w,             hh: th), "title"],
+      [panel(x: 0,        y: my, ww: half,          hh: mh), "list"],
+      [panel(x: half - 1, y: my, ww: w - half + 1,  hh: mh), "preview"],
+      [panel(x: 0,        y: by, ww: w,             hh: bh), "status"]
+    ]
+  end
+
+  def band_offsets(h)
+    top_h = [(h * 0.30).round, 3].max
+    mid_h = [(h * 0.40).round, 3].max
+    mid_y = top_h - 1
+    bot_y = mid_y + mid_h - 1
+    [top_h, mid_h, mid_y, bot_y, h - bot_y]
+  end
+
+  def panel(x:, y:, ww:, hh:) = Thaum::Rect.new(x: x, y: y, width: ww, height: hh)
+
+  def border(canvas:, rect:, theme:)
+    canvas.sub(rect: rect).border(fg: theme.border)
+  end
+
+  def label(canvas:, rect:, label:, theme:)
+    inner = canvas.sub(
+      rect: Thaum::Rect.new(x: rect.x + 1, y: rect.y + 1, width: rect.width - 2, height: rect.height - 2)
+    )
+    inner.text(content: label, fg: theme.dim)
+  end
+end
+
+class LayoutDemoApp
+  include Thaum::App
+
+  def initialize
+    t = Thaum::Themes::SOLARIZED_LIGHT
+    @title    = HeaderItem.new(label: "Layout DSL — region settings demo", color: t.accent)
+    @status   = HeaderItem.new(label: "h:3/h:fill/h:1 outer · w:12/w::fill/w:'20%' min:18 middle", color: t.selection)
+    @clock    = HeaderItem.new(label: "12:34", color: t.border)
+    @nav      = HeaderItem.new(label: "w: 12", color: t.pressed)
+    @aside    = HeaderItem.new(label: "w: '20%'\nmin: 18", color: t.bar_bg)
+    @grid     = Grid.new
+    @hint     = HeaderItem.new(label: " esc to quit — borders inside the grid merge into junctions", color: t.dim)
+  end
+
+  def theme = Thaum::Themes::SOLARIZED_LIGHT
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def partition
+    vertical do
+      region(height: 3)     { header }
+      region(height: :fill) { middle }
+      region(height: 1)     { @hint }
+    end
+  end
+
+  private
+
+  def header
+    horizontal do
+      region(width: "30%") { @title }
+      region(width: :fill) { @status }
+      region(width: 10)    { @clock }
+    end
+  end
+
+  def middle
+    horizontal do
+      region(width: 12)             { @nav }
+      region(width: :fill)          { @grid }
+      region(width: "20%", min: 18) { @aside }
+    end
+  end
+end
+
+Thaum.run(LayoutDemoApp.new)

data/examples/modal.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/modal.rb
+#
+# Press "m" to open a modal. Inside the modal, press Escape (framework-
+# intercepted) or "y"/"n" to dismiss. Outside the modal, Escape quits.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+class Background
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    canvas.text(content: "Press m to open a modal, esc to quit.", fg: theme.fg, align: :center, y: canvas.height / 2)
+    canvas.text(content: "(Modal can be Escape-dismissed.)", fg: theme.dim, align: :center, y: (canvas.height / 2) + 2)
+  end
+end
+
+class Confirm
+  include Thaum::Sigil
+
+  DismissedEvent = Thaum::Event.define(:choice)
+
+  def render(canvas:, theme:)
+    inner = canvas.border(style: :rounded, fg: theme.warning_fg, bg: theme.bg)
+    inner.fill(bg: theme.bg)
+    inner.text(content: "Are you sure?", fg: theme.warning_fg, align: :center, y: 1)
+    inner.text(content: "[y]es   [n]o   Esc cancels", fg: theme.muted_fg, align: :center, y: 3)
+  end
+
+  def on_key(event)
+    case event.key
+    when "y", "n" then emit(DismissedEvent.new(choice: event.key))
+    else emit(event)
+    end
+  end
+end
+
+class ModalApp
+  include Thaum::App
+
+  def initialize
+    @choice_display = Thaum::Text.new(content: "Modal choice: none", align: :center)
+    @background = Background.new
+  end
+
+  def partition
+    vertical do
+      region(height: 1) { @choice_display }
+      region(height: :fill) { @background }
+    end
+  end
+
+  def on_key(event)
+    case event.key
+    when :escape then quit
+    when "m" then show_modal(sigil: Confirm.new, width: 36, height: 7)
+    end
+  end
+
+  def on_event(event)
+    case event
+    when Confirm::DismissedEvent
+      @choice_display.content = "Modal choice: #{event.choice}"
+      hide_modal
+    else
+      super
+    end
+  end
+end
+
+Thaum.run(ModalApp.new)

data/examples/mouse.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/mouse.rb
+#
+# Click in either pane to bump its counter. Scroll wheel anywhere bumps
+# the global tally. Press esc to quit.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+class ClickPane
+  include Thaum::Sigil
+
+  attr_reader :clicks
+
+  def initialize(label)
+    @label  = label
+    @clicks = 0
+  end
+
+  def on_mouse(event)
+    case event.action
+    when :press then @clicks += 1
+    end
+  end
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: focused? ? theme.pressed : theme.bg)
+    center = canvas.height / 2
+    canvas.text(content: @label, fg: theme.fg, align: :center, y: center - 1)
+    canvas.text(content: "clicks: #{@clicks}", fg: theme.fg, align: :center, y: center + 1)
+  end
+end
+
+class MouseApp
+  include Thaum::App
+
+  def initialize
+    @left    = ClickPane.new("LEFT")
+    @right   = ClickPane.new("RIGHT")
+    @scrolls = 0
+  end
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def on_mouse(event)
+    @scrolls += 1 if event.action == :scroll
+  end
+
+  def partition
+    horizontal do
+      region(width: :fill) { @left }
+      region(width: :fill) { @right }
+    end
+  end
+end
+
+Thaum.run(MouseApp.new)