bubblezone 0.1.0-x86-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85a0fab73e612b6ccd5423e61f5ec8e532ea4a0ccb140fb5451aba4b276f4293
+  data.tar.gz: d1dea9fef2788480cf9d04742d476fcab63b558d33d167e818f859a9be6c533a
+SHA512:
+  metadata.gz: de9c32d6029954e541543d817707524e791cba6feec672c343aae966ac9770a1d4e5188d1d2856495f1d3caf87e1a8a44c6de1d20009013fc9da4870ec680c00
+  data.tar.gz: d69e60cfd2c7b02805c172a88a6acf290fcd04e9bb1141e8bb11277e28ba9852bdcc0d2f5bfa60548ed0aed1f33d1fd4ad4fd882a0f592f57d0408822e0644a1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Marco Roth
+
+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,370 @@
+<div align="center">
+  <h1>Bubblezone for Ruby</h1>
+  <h4>Helper utility for <a href="https://github.com/marcoroth/bubbletea-ruby">Bubble Tea</a>, allowing easy mouse event tracking in terminal applications.</h4>
+
+  <p>
+    <a href="https://rubygems.org/gems/bubblezone"><img alt="Gem Version" src="https://img.shields.io/gem/v/bubblezone"></a>
+    <a href="https://github.com/marcoroth/bubblezone-ruby/blob/main/LICENSE.txt"><img alt="License" src="https://img.shields.io/github/license/marcoroth/bubblezone-ruby"></a>
+  </p>
+
+  <p>Ruby bindings for <a href="https://github.com/lrstanley/bubblezone">lrstanley/bubblezone</a>.<br/>Track clickable regions in terminal UIs. Built for use with <a href="https://github.com/marcoroth/bubbletea-ruby">Bubble Tea</a> and <a href="https://github.com/marcoroth/lipgloss-ruby">Lipgloss</a>.</p>
+</div>
+
+## Installation
+
+**Add to your Gemfile:**
+
+```ruby
+gem "bubblezone"
+```
+
+**Or install directly:**
+
+```bash
+gem install bubblezone
+```
+
+## Usage
+
+### Basic Zone Marking
+
+**Initialize the global zone manager:**
+
+```ruby
+require "bubblezone"
+
+Bubblezone.new_global
+```
+
+**Mark a region with an ID:**
+
+```ruby
+button = Bubblezone.mark("my_button", "Click Me")
+```
+
+**Build your layout and scan to register zones:**
+
+```ruby
+layout = "Header\n#{button}\nFooter"
+output = Bubblezone.scan(layout)
+puts output
+```
+
+**Output:**
+
+```
+Header
+Click Me
+Footer
+```
+
+### Getting Zone Information
+
+**Get zone info by ID:**
+
+```ruby
+zone = Bubblezone.get("my_button")
+```
+
+**Check zone bounds:**
+
+```ruby
+if zone
+  puts "Zone bounds: (#{zone.start_x}, #{zone.start_y}) to (#{zone.end_x}, #{zone.end_y})"
+end
+```
+
+### Checking Mouse Coordinates
+
+**Get coordinates from mouse event:**
+
+```ruby
+x, y = message.x, message.y
+```
+
+**Check if coordinates are within a zone:**
+
+```ruby
+zone = Bubblezone.get("my_button")
+if zone&.in_bounds?(x, y)
+  puts "Button clicked!"
+end
+```
+
+### Iterating Over Zones
+
+**Iterate over all zones containing the coordinates:**
+
+```ruby
+Bubblezone.each_in_bounds(x, y) do |id, zone|
+  puts "Hit zone: #{id}"
+end
+```
+
+**Check if any zone contains the coordinates:**
+
+```ruby
+if Bubblezone.any_in_bounds?(x, y)
+  puts "Something was clicked"
+end
+```
+
+**Get the first matching zone:**
+
+```ruby
+result = Bubblezone.find_in_bounds(x, y)
+if result
+  id, zone = result
+  puts "First hit: #{id}"
+end
+```
+
+### Zone Prefixes
+
+**Prevent ID conflicts between components:**
+
+```ruby
+class MyComponent
+  def initialize
+    @prefix = Bubblezone.new_prefix
+  end
+
+  def view
+    items = ["Apple", "Banana", "Cherry"]
+    items.map.with_index do |item, i|
+      Bubblezone.mark("#{@prefix}#{i}", item)
+    end.join("\n")
+  end
+end
+```
+
+### Manager Instances
+
+**Create a dedicated manager:**
+
+```ruby
+manager = Bubblezone::Manager.new
+```
+
+**Use the same API as the global manager:**
+
+```ruby
+marked = manager.mark("zone_id", "Content")
+output = manager.scan(marked)
+zone = manager.get("zone_id")
+```
+
+**Iterate zones:**
+
+```ruby
+manager.each_in_bounds(x, y) { |id, zone| ... }
+```
+
+**Clean up when done:**
+
+```ruby
+manager.close
+```
+
+### Integration with Bubbletea
+
+**Handle mouse clicks in a Bubbletea model:**
+
+```ruby
+require "bubbletea"
+require "bubblezone"
+
+Bubblezone.new_global
+
+class ClickableApp
+  include Bubbletea::Model
+
+  ITEMS = ["Option A", "Option B", "Option C"]
+
+  def initialize
+    @selected = nil
+    @prefix = Bubblezone.new_prefix
+  end
+
+  def init
+    [self, nil]
+  end
+
+  def update(message)
+    case message
+    when Bubbletea::MouseMessage
+      if message.release? && (message.left? || message.button == 0)
+        result = Bubblezone.find_in_bounds(message.x, message.y)
+        if result
+          id, _zone = result
+          @selected = id.sub(@prefix, "").to_i
+        end
+      end
+      [self, nil]
+    when Bubbletea::KeyMessage
+      return [self, Bubbletea.quit] if message.to_s == "q"
+      [self, nil]
+    else
+      [self, nil]
+    end
+  end
+
+  def view
+    lines = ITEMS.map.with_index do |item, i|
+      marker = i == @selected ? "[x]" : "[ ]"
+      content = "#{marker} #{item}"
+      Bubblezone.mark("#{@prefix}#{i}", content)
+    end
+
+    Bubblezone.scan(lines.join("\n"))
+  end
+end
+
+Bubbletea.run(ClickableApp.new, alt_screen: true, mouse_cell_motion: true)
+```
+
+### Integration with Lipgloss
+
+**Style your content first:**
+
+```ruby
+require "lipgloss"
+require "bubblezone"
+
+Bubblezone.new_global
+
+button_style = Lipgloss::Style.new
+  .background("#7D56F4")
+  .foreground("#FFFFFF")
+  .padding(0, 3)
+```
+
+**Mark the fully styled content:**
+
+```ruby
+styled_button = button_style.render("Click Me")
+clickable_button = Bubblezone.mark("btn", styled_button)
+```
+
+**Scan to register zones:**
+
+```ruby
+output = Bubblezone.scan(clickable_button)
+```
+
+## API Reference
+
+### Module Methods (Global Manager)
+
+| Method | Description |
+|--------|-------------|
+| `Bubblezone.new_global` | Initialize the global zone manager |
+| `Bubblezone.close` | Close the global manager |
+| `Bubblezone.enabled?` | Check if zone tracking is enabled |
+| `Bubblezone.enabled = bool` | Enable/disable zone tracking |
+| `Bubblezone.new_prefix` | Generate a unique zone ID prefix |
+| `Bubblezone.mark(id, text)` | Wrap text with zone markers |
+| `Bubblezone.scan(text)` | Parse zones and strip markers |
+| `Bubblezone.get(id)` | Get ZoneInfo for an ID (or nil) |
+| `Bubblezone.clear(id)` | Remove a stored zone |
+| `Bubblezone.clear_all` | Remove all stored zones |
+| `Bubblezone.zone_ids` | Get array of all tracked zone IDs |
+
+### Iteration Methods
+
+| Method | Description |
+|--------|-------------|
+| `Bubblezone.each_in_bounds(x, y) { \|id, zone\| }` | Yield each zone containing coordinates |
+| `Bubblezone.any_in_bounds?(x, y)` | Check if any zone contains coordinates |
+| `Bubblezone.find_in_bounds(x, y)` | Get first `[id, zone]` pair, or nil |
+
+### Manager Class
+
+| Method | Description |
+|--------|-------------|
+| `Manager.new` | Create a new zone manager |
+| `#close` | Close the manager |
+| `#enabled?` / `#enabled=` | Get/set enabled state |
+| `#new_prefix` | Generate unique prefix |
+| `#mark(id, text)` | Mark text with zone |
+| `#scan(text)` | Parse and strip markers |
+| `#get(id)` | Get zone info |
+| `#clear(id)` | Clear specific zone |
+| `#clear_all` | Clear all zones |
+| `#zone_ids` | Get all zone IDs |
+| `#each_in_bounds(x, y)` | Iterate matching zones |
+| `#any_in_bounds?(x, y)` | Check for any match |
+| `#find_in_bounds(x, y)` | Get first match |
+
+### ZoneInfo Class
+
+| Method | Description |
+|--------|-------------|
+| `#start_x`, `#start_y` | Zone start coordinates |
+| `#end_x`, `#end_y` | Zone end coordinates |
+| `#in_bounds?(x, y)` | Check if coordinates are within zone |
+| `#zero?` | Check if zone has no position data |
+| `#pos(x, y)` | Get relative position within zone |
+
+## Important Notes
+
+### Zone Processing is Asynchronous
+
+The Go bubblezone library processes zones asynchronously. After calling `scan`, there may be a brief delay before zones are available via `get`. In interactive applications with Bubbletea, this is typically not an issue as mouse events occur after rendering.
+
+### Coordinate Systems
+
+When using `alt_screen: true` with Bubbletea, mouse coordinates are relative to (0, 0) at the top-left of the screen, matching zone coordinates exactly. Without alt screen, you may need to account for terminal scroll position.
+
+### Order of Operations
+
+1. Style your content with Lipgloss
+2. Mark the styled content with `Bubblezone.mark`
+3. Build your complete layout
+4. Call `Bubblezone.scan` on the final output
+5. Handle mouse events using `get` or `find_in_bounds`
+
+## Development
+
+**Requirements:**
+- Go 1.23+
+- Ruby 3.2+
+
+**Install dependencies:**
+
+```bash
+bundle install
+```
+
+**Build the Go library and compile the extension:**
+
+```bash
+bundle exec rake compile
+```
+
+**Run tests:**
+
+```bash
+bundle exec rake test
+```
+
+**Run demos:**
+
+```bash
+./demo/clickable_alt
+./demo/clickable_list
+./demo/clickable_simple
+./demo/full_layout
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/marcoroth/bubblezone-ruby.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.
+
+## Acknowledgments
+
+This gem wraps [lrstanley/bubblezone](https://github.com/lrstanley/bubblezone), which provides zone tracking for terminal UIs and builds on the excellent [Charm](https://charm.sh) ecosystem, including [lipgloss](https://github.com/marcoroth/lipgloss-ruby) and [bubbletea](https://github.com/marcoroth/bubbletea-ruby).

data/bubblezone.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/bubblezone/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "bubblezone"
+  spec.version = Bubblezone::VERSION
+  spec.authors = ["Marco Roth"]
+  spec.email = ["marco.roth@intergga.ch"]
+
+  spec.summary = "Ruby bindings for bubblezone, helper utility for BubbleTea, allowing easy mouse event tracking."
+  spec.description = "Ruby bindings for the bubblezone, providing zone management for terminal applications with mouse support."
+  spec.homepage = "https://github.com/marcoroth/bubblezone-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/marcoroth/bubblezone-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/marcoroth/bubblezone-ruby/releases"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir[
+    "bubblezone.gemspec",
+    "LICENSE.txt",
+    "README.md",
+    "lib/**/*.rb",
+    "ext/**/*.{c,h,rb}",
+    "go/**/*.{go,mod,sum}",
+    "go/build/**/*"
+  ]
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.extensions = ["ext/bubblezone/extconf.rb"]
+
+  spec.add_dependency "rake-compiler", "~> 1.2"
+end

data/ext/bubblezone/extconf.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+extension_name = "bubblezone"
+
+def detect_platform
+  cpu = RbConfig::CONFIG["host_cpu"]
+  os = RbConfig::CONFIG["host_os"]
+
+  arch = case cpu
+         when /aarch64|arm64/ then "arm64"
+         when /x86_64|amd64/ then "amd64"
+         when /arm/ then "arm"
+         when /i[3-6]86/ then "386"
+         else cpu
+         end
+
+  goos = case os
+         when /darwin/ then "darwin"
+         when /mswin|mingw/ then "windows"
+         else "linux"
+         end
+
+  "#{goos}_#{arch}"
+end
+
+platform = detect_platform
+go_lib_dir = File.expand_path("../../go/build/#{platform}", __dir__)
+
+puts "Looking for Go library in: #{go_lib_dir}"
+
+unless File.exist?(File.join(go_lib_dir, "libbubblezone.a"))
+  abort <<~ERROR
+    Could not find libbubblezone.a for platform #{platform}
+
+    Please build the Go archive first:
+      cd go && go build -buildmode=c-archive -o build/#{platform}/libbubblezone.a .
+
+    Or run:
+      bundle exec rake go:build
+  ERROR
+end
+
+$LDFLAGS << " -L#{go_lib_dir}"
+$INCFLAGS << " -I#{go_lib_dir}"
+
+$LOCAL_LIBS << " #{go_lib_dir}/libbubblezone.a"
+
+case RbConfig::CONFIG["host_os"]
+when /darwin/
+  $LDFLAGS << " -framework CoreFoundation -framework Security -framework SystemConfiguration"
+  $LDFLAGS << " -lresolv"
+when /linux/
+  $LDFLAGS << " -lpthread -lm -ldl"
+  $LDFLAGS << " -lresolv" if find_library("resolv", "res_query")
+end
+
+$srcs = [
+  "extension.c",
+  "manager.c",
+  "zone_info.c",
+]
+
+create_makefile("#{extension_name}/#{extension_name}")

data/ext/bubblezone/extension.c

@@ -0,0 +1,107 @@
+#include "extension.h"
+
+VALUE mBubblezone;
+VALUE cManager;
+VALUE cZoneInfo;
+
+static VALUE bubblezone_new_global_rb(VALUE self) {
+  bubblezone_new_global();
+  return Qnil;
+}
+
+static VALUE bubblezone_global_close_rb(VALUE self) {
+  bubblezone_global_close();
+  return Qnil;
+}
+
+static VALUE bubblezone_global_set_enabled_rb(VALUE self, VALUE enabled) {
+  bubblezone_global_set_enabled(RTEST(enabled) ? 1 : 0);
+  return enabled;
+}
+
+static VALUE bubblezone_global_enabled_rb(VALUE self) {
+  return bubblezone_global_enabled() ? Qtrue : Qfalse;
+}
+
+static VALUE bubblezone_global_new_prefix_rb(VALUE self) {
+  char *prefix = bubblezone_global_new_prefix();
+  VALUE rb_prefix = rb_utf8_str_new_cstr(prefix);
+  bubblezone_free(prefix);
+
+  return rb_prefix;
+}
+
+static VALUE bubblezone_global_mark_rb(VALUE self, VALUE zone_id, VALUE text) {
+  Check_Type(zone_id, T_STRING);
+  Check_Type(text, T_STRING);
+
+  char *result = bubblezone_global_mark(StringValueCStr(zone_id), StringValueCStr(text));
+  VALUE rb_result = rb_utf8_str_new_cstr(result);
+  bubblezone_free(result);
+
+  return rb_result;
+}
+
+static VALUE bubblezone_global_clear_rb(VALUE self, VALUE zone_id) {
+  Check_Type(zone_id, T_STRING);
+  bubblezone_global_clear(StringValueCStr(zone_id));
+  return Qnil;
+}
+
+static VALUE bubblezone_global_get_rb(VALUE self, VALUE zone_id) {
+  Check_Type(zone_id, T_STRING);
+
+  unsigned long long handle = bubblezone_global_get(StringValueCStr(zone_id));
+
+  if (handle == 0) {
+    return Qnil;
+  }
+
+  return zone_info_wrap(cZoneInfo, handle);
+}
+
+static VALUE bubblezone_global_scan_rb(VALUE self, VALUE text) {
+  Check_Type(text, T_STRING);
+
+  char *result = bubblezone_global_scan(StringValueCStr(text));
+  VALUE rb_result = rb_utf8_str_new_cstr(result);
+  bubblezone_free(result);
+
+  return rb_result;
+}
+
+static VALUE bubblezone_upstream_version_rb(VALUE self) {
+  char *version = bubblezone_upstream_version();
+  VALUE rb_version = rb_utf8_str_new_cstr(version);
+  bubblezone_free(version);
+
+  return rb_version;
+}
+
+static VALUE bubblezone_version_rb(VALUE self) {
+  VALUE gem_version = rb_const_get(self, rb_intern("VERSION"));
+  VALUE upstream_version = bubblezone_upstream_version_rb(self);
+  VALUE format_string = rb_utf8_str_new_cstr("bubblezone v%s (upstream %s) [Go native extension]");
+
+  return rb_funcall(rb_mKernel, rb_intern("sprintf"), 3, format_string, gem_version, upstream_version);
+}
+
+__attribute__((__visibility__("default"))) void Init_bubblezone(void) {
+  mBubblezone = rb_define_module("Bubblezone");
+
+  Init_bubblezone_manager();
+  Init_bubblezone_zone_info();
+
+  rb_define_singleton_method(mBubblezone, "new_global", bubblezone_new_global_rb, 0);
+  rb_define_singleton_method(mBubblezone, "close", bubblezone_global_close_rb, 0);
+  rb_define_singleton_method(mBubblezone, "enabled=", bubblezone_global_set_enabled_rb, 1);
+  rb_define_singleton_method(mBubblezone, "enabled?", bubblezone_global_enabled_rb, 0);
+  rb_define_singleton_method(mBubblezone, "new_prefix", bubblezone_global_new_prefix_rb, 0);
+  rb_define_singleton_method(mBubblezone, "mark", bubblezone_global_mark_rb, 2);
+  rb_define_singleton_method(mBubblezone, "clear", bubblezone_global_clear_rb, 1);
+  rb_define_singleton_method(mBubblezone, "get", bubblezone_global_get_rb, 1);
+  rb_define_singleton_method(mBubblezone, "scan", bubblezone_global_scan_rb, 1);
+
+  rb_define_singleton_method(mBubblezone, "upstream_version", bubblezone_upstream_version_rb, 0);
+  rb_define_singleton_method(mBubblezone, "version", bubblezone_version_rb, 0);
+}

data/ext/bubblezone/extension.h

@@ -0,0 +1,36 @@
+#ifndef BUBBLEZONE_EXTENSION_H
+#define BUBBLEZONE_EXTENSION_H
+
+#include <ruby.h>
+#include "libbubblezone.h"
+
+extern VALUE mBubblezone;
+extern VALUE cManager;
+extern VALUE cZoneInfo;
+
+typedef struct {
+  unsigned long long handle;
+} bubblezone_manager_t;
+
+typedef struct {
+  unsigned long long handle;
+} bubblezone_zone_info_t;
+
+#define GET_MANAGER(self, manager) \
+  bubblezone_manager_t *manager; \
+  TypedData_Get_Struct(self, bubblezone_manager_t, &manager_type, manager)
+
+#define GET_ZONE_INFO(self, zone_info) \
+  bubblezone_zone_info_t *zone_info; \
+  TypedData_Get_Struct(self, bubblezone_zone_info_t, &zone_info_type, zone_info)
+
+extern const rb_data_type_t manager_type;
+extern const rb_data_type_t zone_info_type;
+
+VALUE manager_wrap(VALUE klass, unsigned long long handle);
+VALUE zone_info_wrap(VALUE klass, unsigned long long handle);
+
+void Init_bubblezone_manager(void);
+void Init_bubblezone_zone_info(void);
+
+#endif