feat(tui): overlay positioning API with CSS-like values

Add OverlayOptions for configurable positioning (anchor, margins, offsets,
percentages). Add OverlayHandle for programmatic visibility control with
hide/setHidden/isHidden. Add visible callback for responsive overlays.

Extension API: ctx.ui.custom() now accepts overlayOptions and onHandle callback.

Examples: overlay-qa-tests.ts (10 test commands), doom-overlay (DOOM at 35 FPS).
This commit is contained in:
Nico Bailon 2026-01-12 22:12:56 -08:00
parent d29f268f46
commit a4ccff382c
22 changed files with 1344 additions and 103 deletions

View file

@ -21,6 +21,7 @@ import type {
EditorComponent,
EditorTheme,
KeyId,
OverlayHandle,
OverlayOptions,
SlashCommand,
} from "@mariozechner/pi-tui";
@ -1260,7 +1261,11 @@ export class InteractiveMode {
keybindings: KeybindingsManager,
done: (result: T) => void,
) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>,
options?: { overlay?: boolean; overlayOptions?: OverlayOptions | (() => OverlayOptions) },
options?: {
overlay?: boolean;
overlayOptions?: OverlayOptions | (() => OverlayOptions);
onHandle?: (handle: OverlayHandle) => void;
},
): Promise<T> {
const savedText = this.editor.getText();
const isOverlay = options?.overlay ?? false;
@ -1309,7 +1314,9 @@ export class InteractiveMode {
const w = (component as { width?: number }).width;
return w ? { width: w } : undefined;
};
this.ui.showOverlay(component, resolveOptions());
const handle = this.ui.showOverlay(component, resolveOptions());
// Expose handle to caller for visibility control
options?.onHandle?.(handle);
} else {
this.editorContainer.clear();
this.editorContainer.addChild(component);