bubblezone

Crystal port of bubblezone - mouse interaction zones for terminal UI

The original Go version is included as a submodule in bubblezone_go/ for reference.

Problem

Term2 and lipgloss allow you to build extremely fast terminal interfaces, in a semantic and scalable way. Through abstracting layout, colors, events, and more, it's very easy to build a user-friendly application. Term2 also supports mouse events, either through the "basic" mouse events, like left click, right click, wheel up and wheel down.

This works great for a single-component application, where the state is managed in one location. However, when you start expanding your application, where components have various children, and those children have children, calculating mouse events and determining which component was clicked becomes complicated, and rather tedious.

Solution

BubbleZone is one solution to this problem. BubbleZone allows you to wrap your components in zero-printable-width (to not impact lipgloss.width() calculations) identifiers. Additionally, there is a scan method that wraps the entire application, stores the offsets of those identifiers as zones, and then removes them from the resulting output.

Any time there is a mouse event, pass it down to all children, thus allowing you to easily check if the event is within the bounds of the components zone. This makes it very simple to do things like focusing on various components, clicking "buttons", and more.

Features

• ✔️ It's fast -- given it has to process this information for every render, we focus on performance where possible.
• ✔️ It doesn't impact width calculations when using lipgloss.width().
• ✔️ It's simple -- easily determine offset or if an event was within the bounds of a zone.
• ✔️ Want the mouse event position relative to the component? Easy!
• ✔️ Provides an optional global manager, when you have full access to all components, so you don't have to inject it as a dependency to all components.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     bubblezone:
       github: dsisnero/bubblezone
   

2. Run shards install

Usage

require "bubblezone"

TODO: Write Crystal-specific usage instructions here

Development

TODO: Write development instructions here

Contributing

1. Fork it (https://github.com/dsisnero/bubblezone/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Dom - creator and maintainer
• Original Go version by Liam Stanley