feat(widgets): add textarea, left-bordered box, and blocks spinner (#109)

* feat(widgets): add textarea, left-bordered box, and block spinner

- Add Textarea_widget: multiline text input with Shift+Enter for newlines,
  cursor navigation, line joining on backspace/delete, scroll support
- Add render_left_border_box: opencode-style box with colored left border
  and background color
- Add Block spinner style: animated block cursor ([ ] [▌] [█] [▐]) in a box
- Extend Spinner_widget with style parameter (Dots or Block)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat(widgets): add textarea, left-bordered box, and blocks spinner

- Add Textarea_widget: multiline text input with Shift+Enter for newlines,
  cursor navigation, line joining on backspace/delete, scroll support
- Add render_left_border_box: box with colored left border and background,
  useful for context sections or quoted content
- Add Blocks spinner style: size + color gradient progression trail
  - Lead: ■ (large), trail: ▪ • · (shrinking)
  - Configurable direction (Left/Right)
  - Configurable block count

Co-Authored-By: Claude <noreply@anthropic.com>

* feat(input): add Alt+Enter key parsing for textarea newlines

Replace ShiftEnter with AltEnter since most terminals don't send
distinct escape sequences for Shift+Enter. Alt+Enter (ESC followed
by newline) is universally supported.

- Add AltEnter key variant to input_parser
- Update textarea widget to use A-Enter/Alt-Enter keys
- Update demos and documentation
- Bump version to 0.3.1

Co-Authored-By: Claude <noreply@anthropic.com>

* feat(widgets): add mouse support (wheel scroll + click)

Add comprehensive mouse support to widgets:
- New Mouse helper module with event parsing utilities
- Pager: wheel scroll, click to position cursor (in cursor mode)
- Select: wheel scroll, click to select item
- File Browser: wheel scroll, click to select entry
- Textbox: click to position cursor
- Textarea: wheel scroll, click to position cursor
- Tabs: click to select tab
- Breadcrumbs: click on crumb to navigate
- Button/Link: click to activate/navigate
- Checkbox/Radio/Switch: click to toggle

Co-Authored-By: Claude <noreply@anthropic.com>

* feat(demos): wire mouse events to launcher and widget demos

- Launcher: wheel scroll moves selection, click opens demo
- Modals (select, poly_select, file_browser, textbox): forward mouse
  events via handle_modal_key since they don't parse as typed keys
- Demos (pager, link, switch, validated_textbox): forward mouse events
  to their widgets

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(mouse): improve click handling and add double-click support

- Fix click vs selection: single clicks now dispatch to widgets instead
  of starting text selection. Actual text selection requires dragging.
- Add double-click/triple-click event types (DoubleClick:, TripleClick:)
  which are passed to widgets for handling
- Fix Escape key handling in all demos: use Keys.Escape variant instead
  of Char "Esc" which was never matched
- Add modal click coordinate translation: store rendered modal position
  and translate screen coordinates to widget-relative coordinates
- File browser: single click selects, double-click opens folder/file
- Select widget: fix click handling to account for scroll offset and
  top indicator line

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(matrix): remove unnecessary mark_all_dirty from mouse handlers

Remove mark_all_dirty calls from MousePress, Mouse release, and MouseDrag
handlers to fix screen flickering on mouse events.

The back buffer is cleared and re-rendered every tick (30 TPS), with
apply_highlight adding selection styling based on current state. The
render domain (60 FPS) diffs front vs back and updates only changed
cells. When selection changes or clears, the diff naturally detects
and updates affected cells without needing a forced full redraw.

Co-Authored-By: Claude <noreply@anthropic.com>

* feat(box_widget): add per-side border colors

Add border_colors parameter with c_top, c_bottom, c_left, c_right fields
to allow different colors for each border side. Useful for indicating
multiple states (e.g., selection on top/left, status on bottom/right).

Corner colors prefer top/bottom colors when both adjacent sides have colors.
When border_colors is provided, it takes precedence over the color parameter.

* fix(pager): add ANSI reset and wrap-aware scrolling

- Add ANSI reset at end of each rendered line to prevent color spill
- Fix ensure_cursor_visible to account for wrapped line heights

* fix(mouse): write enable sequence to /dev/tty for consistency

The enable_mouse function was writing to stdout while all other matrix
driver terminal operations write to /dev/tty. This inconsistency could
cause buffering mismatches and race conditions leading to screen flicker.

Now enable_mouse writes to tty_out_fd first (with tcdrain to ensure
delivery), then to stdout as fallback, matching the pattern used by
disable_mouse for reliability.

Co-Authored-By: Claude <noreply@anthropic.com>

* feat(signals): add install_signals' with optional SIGINT handling

Add install_signals' variant that accepts ~handle_sigint:bool parameter.
When false, SIGINT is not intercepted, allowing apps to receive Ctrl+C
as a key event instead of immediate exit.

The original install_signals is preserved unchanged (delegates to
install_signals' with ~handle_sigint:true).

* fix(matrix): remove screen clear from periodic scrub to prevent flicker

The periodic scrub was clearing the entire screen with ESC[2J before
redrawing, causing visible flicker. Instead, just mark all cells dirty
and let the diff-based renderer overwrite them naturally.

* feat(config): add handle_sigint option to control Ctrl+C behavior

Add handle_sigint field to Matrix_config.t (default: true). When false,
SIGINT is not intercepted, allowing apps to receive Ctrl+C as a key
event ("C-c") instead of immediate exit.

Propagates through Matrix_input.create and Matrix_driver.

* feat(runner): add handle_sigint option to Runner_tui.run

Allows apps to disable SIGINT handling so Ctrl+C is received as a key
event ("C-c") instead of immediately exiting.

* fix(terminal): disable c_isig in raw mode and ignore SIGINT when not handling

Two changes to make Ctrl+C receivable as a key event:
1. Set c_isig=false in raw mode to prevent terminal from generating
   SIGINT on ^C - this allows the character (ASCII 3) to be read
2. When handle_sigint=false, explicitly ignore SIGINT to prevent
   default termination behavior

Together these allow apps to receive Ctrl+C as "C-c" key event.

* docs(changelog): document new widgets and signal updates

Add changelog entries for signal handling options, Box_widget per-side border
colors, and recent driver/mouse/pager fixes on the new-widgets branch.

* chore(release): bump new-widgets to 0.3.2

* fix: copyright year, comment typo, spinner glyph and docs

- Fix copyright year 2025 → 2026 in mouse.ml/mli
- Fix comment "Shift+Enter" → "Alt+Enter" in textarea_widget.ml
- Fix spinner_widget.mli docs: Blocks renders a single line, not 3
- Implement glyph parameter in render_blocks_glyph (was ignored)
  Circle: ● ○ • · and Dot: • ∙ · · variants now work

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: mathiasbourgoin

CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - Unreleased
+
+### Added
+
+- **Textarea widget** (`miaou_widgets_input.Textarea_widget`): multiline text input with cursor navigation, line joining, and scroll support. Use Alt+Enter to insert newlines.
+- **Left-bordered box** (`Widgets.render_left_border_box`): display helper for context/quote blocks with colored left border and optional background.
+- **Blocks spinner style** (`Spinner_widget.Blocks`): animated spinner with size+color gradient progression trail, configurable direction and block count.
+- **Alt+Enter key parsing** (`Input_parser.AltEnter`): universally-supported newline insertion key for textarea widgets.
+- **Mouse helper module** (`Miaou_helpers.Mouse`): utilities for parsing mouse events (clicks, drags, wheel) in widgets.
+- **Mouse support for widgets**: wheel scrolling and click handling added to:
+  - Pager: wheel scroll, click to position cursor (in cursor mode)
+  - Select: wheel scroll, click to select item
+  - File Browser: wheel scroll, click to select entry
+  - Textbox: click to position cursor
+  - Textarea: wheel scroll, click to position cursor
+  - Tabs: click to select tab
+  - Breadcrumbs: click on crumb to navigate
+  - Button: click to activate
+  - Link: click to navigate
+  - Checkbox/Radio/Switch: click to toggle
+
+- **Signal handling control**: optional SIGINT handling via `install_signals'` and `Runner_tui.run` `handle_sigint` option.
+- **Per-side border colors** for `Box_widget` to style each edge independently.
+
+### Changed
+
+- **Input parser**: added `AltEnter` key variant for Alt+Enter detection (ESC followed by newline).
+
+### Fixed
+
+- **Matrix driver scrub**: avoid screen clear during periodic scrub to reduce flicker.
+- **Terminal raw mode**: disable `c_isig` and ignore SIGINT when not handling it.
+- **Mouse interactions**: consistent enable sequence via `/dev/tty`, improved click handling, and double-click support.
+- **Pager**: add ANSI reset and wrap-aware scrolling.
+
 ## [0.3.0] - Unreleased
 
 ### Breaking Changes

dune-project

@@ -1,6 +1,6 @@
 (lang dune 3.15)
 (name miaou)
-(version 0.3.0)
+(version 0.3.2)
 (generate_opam_files true)
 (license MIT)
 

example/demos/bar_chart/page.ml

@@ -64,9 +64,7 @@ module Inner = struct
 
   let handle_key s key_str ~size:_ =
     match Miaou.Core.Keys.of_string key_str with
-    | Some (Miaou.Core.Keys.Char "Esc") | Some (Miaou.Core.Keys.Char "Escape")
-      ->
-        go_back s
+    | Some Miaou.Core.Keys.Escape -> go_back s
     | Some (Miaou.Core.Keys.Char " ") -> randomize_data s
     | _ -> s
 

example/demos/box_widget/page.ml

@@ -55,8 +55,18 @@ module Inner = struct
     let ascii_box =
       BW.render ~title:"ASCII" ~style:Ascii ~width:box_w "Fallback style"
     in
+    (* Left-bordered box *)
+    let left_border_box =
+      W.render_left_border_box
+        ~border_color:75
+        ~bg_color:236
+        ~cols:box_w
+        "Left-bordered box\nWith colored bg\nFor context/quotes"
+    in
     let left_col = single_box ^ "\n\n" ^ double_box ^ "\n\n" ^ ascii_box in
-    let right_col = rounded_box ^ "\n\n" ^ nested_box in
+    let right_col =
+      rounded_box ^ "\n\n" ^ nested_box ^ "\n\n" ^ left_border_box
+    in
     let left_child =
       {
         Flex.render = (fun ~size:_ -> left_col);

example/demos/braille/page.ml

@@ -120,9 +120,7 @@ module Inner = struct
 
   let handle_key s key_str ~size:_ =
     match Miaou.Core.Keys.of_string key_str with
-    | Some (Miaou.Core.Keys.Char "Esc") | Some (Miaou.Core.Keys.Char "Escape")
-      ->
-        go_back s
+    | Some Miaou.Core.Keys.Escape -> go_back s
     | Some (Miaou.Core.Keys.Char k) when String.lowercase_ascii k = "b" ->
         let mode = match s.mode with ASCII -> Braille | Braille -> ASCII in
         {s with mode}

example/demos/breadcrumbs/page.ml

@@ -60,9 +60,7 @@ module Inner = struct
 
   let handle_key s key_str ~size:_ =
     match Miaou.Core.Keys.of_string key_str with
-    | Some (Miaou.Core.Keys.Char "Esc") | Some (Miaou.Core.Keys.Char "Escape")
-      ->
-        go_back s
+    | Some Miaou.Core.Keys.Escape -> go_back s
     | _ ->
         let trail, handled =
           Breadcrumbs.handle_event ~bubble_unhandled:true s.trail ~key:key_str

example/demos/button/page.ml

@@ -45,9 +45,7 @@ module Inner = struct
     let button, fired = Button.handle_key s.button ~key:key_str in
     let clicks = if fired then s.clicks + 1 else s.clicks in
     match Miaou.Core.Keys.of_string key_str with
-    | Some (Miaou.Core.Keys.Char "Esc") | Some (Miaou.Core.Keys.Char "Escape")
-      ->
-        go_back {s with button; clicks}
+    | Some Miaou.Core.Keys.Escape -> go_back {s with button; clicks}
     | _ -> {s with button; clicks}
 
   let move s _ = s

example/demos/canvas/page.ml

@@ -244,9 +244,7 @@ module Inner = struct
 
   let handle_key s key_str ~size:_ =
     match Miaou.Core.Keys.of_string key_str with
-    | Some (Miaou.Core.Keys.Char "Esc") | Some (Miaou.Core.Keys.Char "Escape")
-      ->
-        go_back s
+    | Some Miaou.Core.Keys.Escape -> go_back s
     | Some (Miaou.Core.Keys.Char k) when String.lowercase_ascii k = "b" ->
         let border_idx = (s.border_idx + 1) mod Array.length border_styles in
         {s with border_idx}

example/demos/card_sidebar/page.ml

@@ -54,9 +54,7 @@ module Inner = struct
 
   let handle_key s key_str ~size:_ =
     match Miaou.Core.Keys.of_string key_str with
-    | Some (Miaou.Core.Keys.Char "Esc") | Some (Miaou.Core.Keys.Char "Escape")
-      ->
-        go_back s
+    | Some Miaou.Core.Keys.Escape -> go_back s
     | Some Miaou.Core.Keys.Tab
     | Some (Miaou.Core.Keys.Char "Tab")
     | Some (Miaou.Core.Keys.Char "NextPage") ->

example/demos/checkbox/page.ml

@@ -79,9 +79,7 @@ module Inner = struct
 
   let handle_key s key_str ~size:_ =
     match Miaou.Core.Keys.of_string key_str with
-    | Some (Miaou.Core.Keys.Char "Esc") | Some (Miaou.Core.Keys.Char "Escape")
-      ->
-        go_back s
+    | Some Miaou.Core.Keys.Escape -> go_back s
     | Some Miaou.Core.Keys.Tab | Some (Miaou.Core.Keys.Char "Tab") ->
         let focus, _ = Focus_chain.handle_key s.focus ~key:"Tab" in
         {s with focus}