Merge branch 'main' into feat/tui-overlay-options

packages/tui/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.45.5] - 2026-01-13
+
+## [0.45.4] - 2026-01-13
+
+## [0.45.3] - 2026-01-13
+
+## [0.45.2] - 2026-01-13
+
+## [0.45.1] - 2026-01-13
+
+## [0.45.0] - 2026-01-13
+
+## [0.44.0] - 2026-01-12
+
 ### Added
 
 - `SettingsListOptions` with `enableSearch` for fuzzy filtering in `SettingsList` ([#643](https://github.com/badlogic/pi-mono/pull/643) by [@ninlds](https://github.com/ninlds))

packages/tui/README.md

@@ -62,16 +62,17 @@ Overlays render components on top of existing content without replacing it. Usef
 
 ```typescript
 // Show overlay with default options (centered, max 80 cols)
-tui.showOverlay(component);
+const handle = tui.showOverlay(component);
 
 // Show overlay with custom positioning and sizing
-tui.showOverlay(component, {
+// Values can be numbers (absolute) or percentage strings (e.g., "50%")
+const handle = tui.showOverlay(component, {
   // Sizing
   width: 60,              // Fixed width in columns
-  widthPercent: 80,       // Width as percentage of terminal (0-100)
+  width: "80%",           // Width as percentage of terminal
   minWidth: 40,           // Minimum width floor
   maxHeight: 20,          // Maximum height in rows
-  maxHeightPercent: 50,   // Maximum height as percentage of terminal
+  maxHeight: "50%",       // Maximum height as percentage of terminal
 
   // Anchor-based positioning (default: 'center')
   anchor: 'bottom-right', // Position relative to anchor point
@@ -79,8 +80,8 @@ tui.showOverlay(component, {
   offsetY: -1,            // Vertical offset from anchor
 
   // Percentage-based positioning (alternative to anchor)
-  rowPercent: 25,         // Vertical position (0=top, 100=bottom)
-  colPercent: 50,         // Horizontal position (0=left, 100=right)
+  row: "25%",             // Vertical position (0%=top, 100%=bottom)
+  col: "50%",             // Horizontal position (0%=left, 100%=right)
 
   // Absolute positioning (overrides anchor/percent)
   row: 5,                 // Exact row position
@@ -88,23 +89,32 @@ tui.showOverlay(component, {
 
   // Margin from terminal edges
   margin: 2,              // All sides
-  margin: { top: 1, right: 2, bottom: 1, left: 2 }
+  margin: { top: 1, right: 2, bottom: 1, left: 2 },
+
+  // Responsive visibility
+  visible: (termWidth, termHeight) => termWidth >= 100  // Hide on narrow terminals
 });
 
+// OverlayHandle methods
+handle.hide();              // Permanently remove the overlay
+handle.setHidden(true);     // Temporarily hide (can show again)
+handle.setHidden(false);    // Show again after hiding
+handle.isHidden();          // Check if temporarily hidden
+
 // Hide topmost overlay
 tui.hideOverlay();
 
-// Check if any overlay is active
+// Check if any visible overlay is active
 tui.hasOverlay();
 ```
 
 **Anchor values**: `'center'`, `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'`, `'top-center'`, `'bottom-center'`, `'left-center'`, `'right-center'`
 
 **Resolution order**:
-1. `width` takes precedence over `widthPercent`
-2. `minWidth` is applied as a floor after width calculation
-3. For position: `row`/`col` > `rowPercent`/`colPercent` > `anchor`
-4. `margin` clamps final position to stay within terminal bounds
+1. `minWidth` is applied as a floor after width calculation
+2. For position: absolute `row`/`col` > percentage `row`/`col` > `anchor`
+3. `margin` clamps final position to stay within terminal bounds
+4. `visible` callback controls whether overlay renders (called each frame)
 
 ### Component Interface
 

packages/tui/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mariozechner/pi-tui",
-	"version": "0.43.0",
+	"version": "0.45.5",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"type": "module",
 	"main": "dist/index.js",