take4-console 0.25.0 → 0.31.0

package/src/Screen/controls/TextBox.mts

@@ -1,7 +1,8 @@
 import type { TextBoxProperties, WindowProperties, StyleId } from '../types.mjs';
-import { BUILTIN_TEXT_PLACEHOLDER, BUILTIN_CURSOR } from '../types.mjs';
+import { BUILTIN_TEXT_PLACEHOLDER, BUILTIN_CURSOR, BUILTIN_TEXT_SELECTION } from '../types.mjs';
 import { Window } from '../Window.mjs';
 import { getRegistry } from '../RegistryHolder.mjs';
+import { VirtualCursor } from '../VirtualCursor.mjs';
 
 /** A single-line text-input widget with scrolling, cursor display, and placeholder support.
  *  Wraps content area inside a single-line border (total height 3 by default).
@@ -9,10 +10,17 @@ import { getRegistry } from '../RegistryHolder.mjs';
 export class TextBox extends Window {
 	private value: string;
 	private cursor: number;
+	/** Anchor of the active selection, or null when no selection is active.
+	 *  Selection spans the half-open range [min(anchor, cursor), max(anchor, cursor)). */
+	private selectionAnchor: number | null;
 	private scrollOffset: number;
 	private placeholder: string;
 	private placeholderStyleId: StyleId;
 	private cursorStyleId: StyleId;
+	private selectionStyleId: StyleId;
+	/** Software-cursor model: blink state + glyph. Always present so the
+	 *  caller can reconfigure at runtime via `getVirtualCursor()`. */
+	private virtualCursor: VirtualCursor;
 
 	/** Invoked after every value change driven by handleKey. Not called by setValue. */
 	private onChange?: (value: string) => void;
@@ -35,6 +43,7 @@ export class TextBox extends Window {
 		this.cursor      = cp?.cursor !== undefined
 			? Math.max(0, Math.min(cp.cursor, this.value.length))
 			: this.value.length;
+		this.selectionAnchor = null;
 
 		this.onChange  = cp?.onChange;
 		this.onSubmit  = cp?.onSubmit;
@@ -43,15 +52,78 @@ export class TextBox extends Window {
 		const reg = getRegistry();
 		this.placeholderStyleId = reg.getNamed(BUILTIN_TEXT_PLACEHOLDER)!;
 		this.cursorStyleId      = reg.getNamed(BUILTIN_CURSOR)!;
+		this.selectionStyleId   = reg.getNamed(BUILTIN_TEXT_SELECTION)!;
+
+		this.virtualCursor = new VirtualCursor({
+			symbol: cp?.cursorSymbol,
+			blink:  cp?.cursorBlink,
+		});
 
 		this.clampScroll();
 	}
 
-	/** Replaces the current value; clamps cursor and scroll to fit. Does NOT fire onChange. */
+	/** Returns the VirtualCursor model so callers can tweak symbol/blink at runtime. */
+	public getVirtualCursor(): VirtualCursor {
+		return this.virtualCursor;
+	}
+
+	/** Replaces the current value; clamps cursor and scroll to fit. Does NOT fire onChange.
+	 *  Any active selection is cleared because the old anchor no longer maps
+	 *  onto the new string. */
 	public setValue(value: string): void {
 		this.value  = value;
 		this.cursor = Math.min(this.cursor, value.length);
+		this.selectionAnchor = null;
+		this.clampScroll();
+		this.markDirty();
+	}
+
+	/** Returns the normalized selection range `{ start, end }` (half-open)
+	 *  when a selection is active and non-empty, otherwise `null`. */
+	public getSelection(): { start: number; end: number } | null {
+		if (this.selectionAnchor === null) return null;
+		const a = this.selectionAnchor;
+		const b = this.cursor;
+		if (a === b) return null;
+		return a < b ? { start: a, end: b } : { start: b, end: a };
+	}
+
+	/** Returns the currently selected substring, or '' when no selection. */
+	public getSelectedText(): string {
+		const sel = this.getSelection();
+		return sel === null ? '' : this.value.slice(sel.start, sel.end);
+	}
+
+	/** Replaces the current selection: sets anchor and cursor, clamping both
+	 *  to the current value length. Passing identical indices clears the
+	 *  selection; callers that want an empty anchor should use `clearSelection()`. */
+	public setSelection(anchor: number, cursor: number): void {
+		const len = this.value.length;
+		const a = Math.max(0, Math.min(anchor, len));
+		const c = Math.max(0, Math.min(cursor, len));
+		this.selectionAnchor = a === c ? null : a;
+		this.cursor = c;
 		this.clampScroll();
+		this.markDirty();
+	}
+
+	/** Selects every character in the current value. No-op when the value is empty. */
+	public selectAll(): void {
+		if (this.value.length === 0) {
+			this.selectionAnchor = null;
+			return;
+		}
+		this.selectionAnchor = 0;
+		this.cursor = this.value.length;
+		this.clampScroll();
+		this.markDirty();
+	}
+
+	/** Drops any active selection without moving the cursor. */
+	public clearSelection(): void {
+		if (this.selectionAnchor === null) return;
+		this.selectionAnchor = null;
+		this.markDirty();
 	}
 
 	/** Replaces the onChange callback (passing undefined clears it). */
@@ -74,10 +146,14 @@ export class TextBox extends Window {
 		return this.value;
 	}
 
-	/** Sets the cursor to the given character index (clamped to valid range). */
+	/** Sets the cursor to the given character index (clamped to valid range).
+	 *  Any active selection is dropped — callers that want to adjust the
+	 *  cursor while keeping the selection must use `setSelection()`. */
 	public setCursor(pos: number): void {
 		this.cursor = Math.max(0, Math.min(pos, this.value.length));
+		this.selectionAnchor = null;
 		this.clampScroll();
+		this.markDirty();
 	}
 
 	/** Returns the current cursor character index. */
@@ -87,9 +163,13 @@ export class TextBox extends Window {
 
 	/** Processes a key string from the terminal input loop and updates value/cursor.
 	 *  Supported special keys: backspace (\x7f), delete (\x1b[3~), left (\x1b[D),
-	 *  right (\x1b[C), home (\x1b[H), end (\x1b[F).
-	 *  Human-readable aliases: 'backspace', 'delete', 'left', 'right', 'home', 'end'.
-	 *  Any single printable character is inserted at the cursor position. */
+	 *  right (\x1b[C), home (\x1b[H), end (\x1b[F), plus their shift-modified
+	 *  CSI variants (`\x1b[1;2D` etc.) which extend the selection, and
+	 *  Ctrl+A (`\x01`) which selects the entire value.
+	 *  Human-readable aliases: 'backspace', 'delete', 'left', 'right', 'home',
+	 *  'end', 'shift+left', 'shift+right', 'shift+home', 'shift+end', 'ctrl+a'.
+	 *  Any single printable character is inserted at the cursor position and
+	 *  replaces the active selection (if any). */
 	public handleKey(key: string): void {
 		if (this.disabled) return;
 
@@ -100,44 +180,125 @@ export class TextBox extends Window {
 		}
 
 		const before = this.value;
+
+		// ── Selection-extending motion (shift + arrow / home / end) ─────────
+		if (key === '\x1b[1;2D' || key === 'shift+left') {
+			this.ensureAnchor();
+			if (this.cursor > 0) this.cursor--;
+			this.finishKey(before);
+			return;
+		}
+		if (key === '\x1b[1;2C' || key === 'shift+right') {
+			this.ensureAnchor();
+			if (this.cursor < this.value.length) this.cursor++;
+			this.finishKey(before);
+			return;
+		}
+		if (key === '\x1b[1;2H' || key === 'shift+home') {
+			this.ensureAnchor();
+			this.cursor = 0;
+			this.finishKey(before);
+			return;
+		}
+		if (key === '\x1b[1;2F' || key === 'shift+end') {
+			this.ensureAnchor();
+			this.cursor = this.value.length;
+			this.finishKey(before);
+			return;
+		}
+		if (key === '\x01' || key === 'ctrl+a') {
+			this.selectAll();
+			this.finishKey(before);
+			return;
+		}
+
 		switch (key) {
 			case '\r': case '\n': case 'enter':
 				this.onSubmit?.(this.value);
 				this.clampScroll();
 				return; // Enter never mutates value by itself in TextBox.
 			case '\x7f': case '\b': case 'backspace':
+				if (this.deleteSelection()) break;
 				if (this.cursor > 0) {
 					this.value = this.value.slice(0, this.cursor - 1) + this.value.slice(this.cursor);
 					this.cursor--;
 				}
 				break;
 			case '\x1b[3~': case 'delete':
+				if (this.deleteSelection()) break;
 				if (this.cursor < this.value.length) {
 					this.value = this.value.slice(0, this.cursor) + this.value.slice(this.cursor + 1);
 				}
 				break;
 			case '\x1b[D': case 'left':
+				// Non-shift left collapses an active selection to its start.
+				if (this.collapseSelection('start')) break;
 				if (this.cursor > 0) this.cursor--;
 				break;
 			case '\x1b[C': case 'right':
+				if (this.collapseSelection('end')) break;
 				if (this.cursor < this.value.length) this.cursor++;
 				break;
 			case '\x1b[H': case 'home':
+				this.selectionAnchor = null;
 				this.cursor = 0;
 				break;
 			case '\x1b[F': case 'end':
+				this.selectionAnchor = null;
 				this.cursor = this.value.length;
 				break;
 			default:
 				if (key.length === 1 && key >= ' ') {
+					this.deleteSelection();
 					this.value = this.value.slice(0, this.cursor) + key + this.value.slice(this.cursor);
 					this.cursor++;
 				}
 		}
+		this.finishKey(before);
+	}
+
+	/** Shared post-key housekeeping: clamp scroll, reset blink phase, fire
+	 *  onChange when the value actually changed. */
+	private finishKey(before: string): void {
 		this.clampScroll();
+		this.virtualCursor.resetPhase();
+		// Every key dispatch is a potential content / selection / cursor
+		// change — flag the window dirty unconditionally so the next
+		// Screen.render() re-emits it. The per-key equality checks in
+		// individual branches are not worth the code; the bounding box is
+		// cheap and we're going to emit at most the whole window.
+		this.markDirty();
 		if (this.value !== before) this.onChange?.(this.value);
 	}
 
+	/** Starts a selection at the current cursor if none is active, so that a
+	 *  subsequent cursor move extends the selection. */
+	private ensureAnchor(): void {
+		if (this.selectionAnchor === null) this.selectionAnchor = this.cursor;
+	}
+
+	/** Removes the selected text when a selection is active; cursor is placed
+	 *  at the start of the deleted range. Returns true when a deletion
+	 *  happened, false otherwise. */
+	private deleteSelection(): boolean {
+		const sel = this.getSelection();
+		if (sel === null) return false;
+		this.value = this.value.slice(0, sel.start) + this.value.slice(sel.end);
+		this.cursor = sel.start;
+		this.selectionAnchor = null;
+		return true;
+	}
+
+	/** Drops an active selection, moving the cursor to the selection's
+	 *  `start` or `end` edge. Returns true when it did so. */
+	private collapseSelection(edge: 'start' | 'end'): boolean {
+		const sel = this.getSelection();
+		if (sel === null) return false;
+		this.cursor = edge === 'start' ? sel.start : sel.end;
+		this.selectionAnchor = null;
+		return true;
+	}
+
 	/** Rebuilds the TextBox: renders text or placeholder, draws cursor. */
 	public override render(): void {
 		this.clear();
@@ -153,12 +314,34 @@ export class TextBox extends Window {
 			this.writeText(visible, { style: this.disabled ? undefined : this.normalStyleId });
 		}
 
-		// Draw cursor when focused.
-		if (this.focused && !this.disabled) {
+		// Paint the selection highlight over any cells that fall inside the
+		// active selection range — run before the cursor so the caret still
+		// shows on top of the highlight.
+		const sel = this.focused && !this.disabled ? this.getSelection() : null;
+		if (sel !== null) {
+			const base = this.normalStyleId;
+			for (let i = sel.start; i < sel.end; i++) {
+				const col = i - this.scrollOffset;
+				if (col < 0 || col >= width) continue;
+				const merged = this.registry.merge(base, this.selectionStyleId);
+				const ch = this.value[i] ?? ' ';
+				this.writeText(ch, { x: col, y: 0, style: merged });
+			}
+		}
+
+		// Draw cursor when focused and the virtual-cursor blink says "on".
+		if (this.focused && !this.disabled && this.virtualCursor.isVisible()) {
 			const cursorX = this.cursor - this.scrollOffset;
 			if (cursorX >= 0 && cursorX < width) {
-				const cursorChar  = this.value[this.cursor] ?? ' ';
-				const cursorStyle = this.registry.merge(this.normalStyleId, this.cursorStyleId);
+				const useSymbol   = this.virtualCursor.hasCustomSymbol();
+				// With a custom glyph we draw the glyph itself (styled with the
+				// normal text style so the symbol's colours stay predictable);
+				// without one we fall back to the legacy inverse-block highlight
+				// painted over the character under the caret.
+				const cursorChar  = useSymbol ? this.virtualCursor.getSymbol() : (this.value[this.cursor] ?? ' ');
+				const cursorStyle = useSymbol
+					? this.normalStyleId
+					: this.registry.merge(this.normalStyleId, this.cursorStyleId);
 				this.writeText(cursorChar, { x: cursorX, y: 0, style: cursorStyle });
 			}
 		}

package/src/Screen/controls/Toast.mts

@@ -0,0 +1,138 @@
+import type { StyleId, ToastPosition, WindowBorder } from '../types.mjs';
+import { BUILTIN_TOAST } from '../types.mjs';
+import { Window } from '../Window.mjs';
+import { Pos } from '../Pos.mjs';
+import { Size } from '../Size.mjs';
+import { getRegistry } from '../RegistryHolder.mjs';
+import { stringWidth } from '../textWidth.mjs';
+
+/** Resolved option bag consumed by the `Toast` constructor. `Screen.toast()`
+ *  fills every field so the control itself never has to re-apply defaults. */
+export interface ToastConstructorOptions {
+  /** Anchor corner (or top/bottom centre). Stored on the instance so the
+   *  enclosing Screen can group toasts by anchor for stacking / re-layout. */
+  position: ToastPosition;
+  /** Pre-registered style used both as the window background and as the
+   *  base style for the toast text. */
+  style: StyleId;
+  /** Border configuration. `false` yields a borderless toast. */
+  border: WindowBorder | boolean;
+  /** Stacking order relative to regular Screen children. */
+  zIndex: number;
+  /** Optional width override for the text row (inner area, without border).
+   *  When undefined the toast auto-sizes to the measured string width. */
+  width: number | undefined;
+}
+
+/** Converts a border option (`true` / `false` / `WindowBorder`) into the
+ *  normalised `{ top, right, bottom, left }` record we need to compute the
+ *  toast's final width and height at construction time. */
+const resolveBorderSides = (border: WindowBorder | boolean): { top: boolean; right: boolean; bottom: boolean; left: boolean } => {
+  if (border === false) return { top: false, right: false, bottom: false, left: false };
+  if (border === true)  return { top: true,  right: true,  bottom: true,  left: true  };
+  const style = border.style;
+  if (style === 'none') return { top: false, right: false, bottom: false, left: false };
+  return {
+    top:    border.top    ?? false,
+    right:  border.right  ?? false,
+    bottom: border.bottom ?? false,
+    left:   border.left   ?? false,
+  };
+};
+
+/** A transient overlay window produced by `Screen.toast()`. Holds the
+ *  message text and the anchor position so the Screen can stack, re-flow,
+ *  and dismiss toasts without leaking that bookkeeping into every caller.
+ *
+ *  The toast is auto-sized: the inner text row is `max(stringWidth(text), 1)`
+ *  cells wide (or `options.width` when explicitly provided), plus one cell
+ *  of horizontal padding on each side and the border insets. Height is
+ *  always one text row plus the vertical border insets — toasts do not
+ *  wrap or stack text vertically. */
+export class Toast extends Window {
+  /** Message rendered inside the toast body. Stored so `setMessage` can
+   *  redraw without re-asking the caller for the original text. */
+  private message: string;
+  /** Anchor corner (or top/bottom centre). Read by `Screen` when re-flowing
+   *  the active-toast stack after a dismissal or terminal resize. */
+  private toastPosition: ToastPosition;
+  /** Style shared between the background fill and the text row. Kept so
+   *  `setMessage` uses the same colour combination the toast launched with. */
+  private toastStyle: StyleId;
+  /** Screen-supplied dismissal hook. Registered after construction via
+   *  `attachDismiss()` so `Toast` does not need a circular import on
+   *  `Screen` to invoke `screen.dismissToast(this)`. */
+  private dismissHandler: (() => void) | undefined;
+
+  /** Builds a Toast with a final size derived from the supplied text and
+   *  option bag. The caller (`Screen.toast()`) is responsible for placing
+   *  the toast inside the Screen via `addChild` and setting the final x/y. */
+  public constructor(text: string, options: ToastConstructorOptions) {
+    const sides       = resolveBorderSides(options.border);
+    const borderW     = (sides.left ? 1 : 0) + (sides.right  ? 1 : 0);
+    const borderH     = (sides.top  ? 1 : 0) + (sides.bottom ? 1 : 0);
+    const innerWidth  = Math.max(1, options.width ?? stringWidth(text));
+    const width       = innerWidth + 2 + borderW; // 1-cell horizontal padding each side.
+    const height      = 1 + borderH;
+
+    super({
+      pos:        Pos.topLeft(),
+      size:       new Size(width, height),
+      background: options.style,
+      border:     options.border,
+      zIndex:     options.zIndex,
+      padding:    { left: 1, right: 1, top: 0, bottom: 0 },
+    });
+
+    this.message       = text;
+    this.toastPosition = options.position;
+    this.toastStyle    = options.style;
+
+    this.writeText(text, { x: 0, y: 0, style: options.style });
+  }
+
+  /** Returns the currently displayed message. */
+  public getMessage(): string {
+    return this.message;
+  }
+
+  /** Returns the resolved style id used for both the background fill and
+   *  the text row. Exposed so tests can verify the toast's paint without
+   *  re-resolving BUILTIN_TOAST by hand. */
+  public getToastStyle(): StyleId {
+    return this.toastStyle;
+  }
+
+  /** Returns the anchor corner the toast was created with. `Screen` uses
+   *  this to group sibling toasts when re-flowing the active stack. */
+  public getToastPosition(): ToastPosition {
+    return this.toastPosition;
+  }
+
+  /** Registers the dismiss callback wired up by `Screen.toast()`. Called
+   *  once immediately after construction so `toast.dismiss()` can trigger
+   *  the full Screen-side teardown (timer cancel, re-flow, onDismiss
+   *  callback) without the Toast needing a direct Screen reference. */
+  public attachDismiss(handler: () => void): void {
+    this.dismissHandler = handler;
+  }
+
+  /** Removes the toast from the Screen it was shown on. Equivalent to
+   *  calling `screen.dismissToast(this)` — the overload exists so callers
+   *  that only kept the Toast reference do not need to remember the owning
+   *  Screen. Safe to call before `attachDismiss()` (no-op) or twice
+   *  (subsequent calls are no-ops because the Screen guards re-dismissal). */
+  public dismiss(): void {
+    this.dismissHandler?.();
+  }
+
+  /** Builds a fallback toast style when the registry did not already have
+   *  `BUILTIN_TOAST` mapped. Extracted as a static helper so `Screen.toast`
+   *  can resolve the style before it knows whether construction will fail. */
+  public static resolveDefaultStyle(): StyleId {
+    const reg = getRegistry();
+    const existing = reg.getNamed(BUILTIN_TOAST);
+    if (existing !== undefined) return existing;
+    return reg.registerNamed(BUILTIN_TOAST, { background: 24, foreground: 231, bold: true });
+  }
+}