pi-openui 0.1.2 → 0.3.0

package/src/blocks/core.ts

@@ -1,10 +1,11 @@
 // Layout and simple components: Stack, Text, Card, Callout, Metric, Button, Choice, Tabs, Faq, Image + tooltips.
-import { textWidth, truncateText, type Rect } from "../diagram/canvas.ts";
+import { textWidth, truncateText, type Cell, type Rect } from "../diagram/canvas.ts";
 import type { El } from "../lang/library.ts";
+import { buildMessage, cleanOther, makeChoice, progress, type Choice } from "./choice.ts";
 import { codeInner } from "./code.ts";
 import { markdownBlock } from "./markdown.ts";
 import { itemId, itemInfo, NOTEABLE, parentKeyOf, WHOLE_ONLY } from "./notes.ts";
-import type { Block, Ctx, Target, Tip } from "./types.ts";
+import type { Block, Ctx, Target, Tip, WState } from "./types.ts";
 import { blank, boxed, cell, fromRows, hstack, padRow, shiftTargets, textCells, vstack, wrapRuns, wrapText } from "./util.ts";
 
 const ROW_GAP: Record<string, number> = { none: 0, xs: 0, s: 0, m: 1, l: 1, xl: 2 };
@@ -36,7 +37,11 @@ export function stack(el: El, width: number, ctx: Ctx, path: string): Block {
 	const gap = COL_GAP[gapTok] ?? 2;
 	const nat = kids.map(natural);
 	const lines: number[][] = [];
-	if (el.props.wrap) {
+	// A row of fixed-size children (tiles, buttons, short text) that cannot sit side by side wraps instead of being squeezed until
+	// their labels are cut. A row with a child that shares the space (a Card, a Table) keeps its old behaviour.
+	const fixedRow = nat.length > 1 && nat.every((n) => n !== null);
+	const overflows = fixedRow && nat.reduce((a, n) => a + (n ?? 0), 0) + gap * (nat.length - 1) > width;
+	if (el.props.wrap || overflows) {
 		let cur: number[] = [];
 		let used = 0;
 		const share = Math.max(14, Math.floor((width - 2 * gap) / 3));
@@ -118,68 +123,129 @@ export function button(el: El, width: number, path: string): Block {
 	return fromRows(Math.max(cells.length, 1), [cells], [t]);
 }
 
+const SEND = "[ Send answers ]";
+const CLEAR = "[ Clear ]";
+
+/** One question: its tag, hint, one row per option and (unless `other` is false) an Other row. A click only stages the answer. */
 export function choice(el: El, width: number, ctx: Ctx, path: string): Block {
-	const p = el.props;
-	const q = String(p.question ?? "");
-	const opts: string[] = p.options ?? [];
-	const picked = ctx.state.picked[path];
-	const head = wrapRuns([{ t: q, role: "choice.q" }], width);
-	const hint = p.hint ? wrapText(String(p.hint), width, "text.muted") : [];
+	const c = makeChoice(el.props);
+	const ans = ctx.state.answers[c.key];
+	const locked = ctx.state.sent;
+	const head = wrapRuns([{ t: c.question, role: "choice.q" }], width);
+	const tag = [textCells(c.multiple ? "Choose all that apply" : "Choose one", "choice.tag")];
+	const hint = el.props.hint ? wrapText(String(el.props.hint), width, "text.muted") : [];
+	const rows: Cell[][] = [...head, ...tag, ...hint];
 	const targets: Target[] = [];
-	const lines: Array<ReturnType<typeof textCells>> = [];
-	const optCells = opts.map((o, i) => {
-		const on = picked === o;
-		return { i, cells: [cell(on ? "●" : "○", on ? "choice.picked" : "choice"), cell(" "), ...textCells(truncateText(o, Math.max(4, width - 3)), on ? "choice.picked" : "choice")] };
-	});
-	const total = optCells.reduce((a, o, k) => a + o.cells.length + (k ? 3 : 0), 0);
-	const baseY = head.length + hint.length;
-	if (total <= width) {
-		let line: typeof lines[number] = [];
-		optCells.forEach((o, k) => {
-			if (k) line.push(cell(" "), cell(" "), cell(" "));
-			targets.push({ id: `choice:${path}:${o.i}`, kind: "choice", rect: { x: line.length, y: baseY, w: o.cells.length, h: 1 }, label: opts[o.i], send: `${q} — ${opts[o.i]}` });
-			line.push(...o.cells);
-		});
-		lines.push(line);
+	const row = (on: boolean, label: string, index: number | "other") => {
+		const role = on ? "choice.picked" : locked ? "choice.locked" : "choice";
+		const mark = c.multiple ? (on ? "[✓]" : "[ ]") : on ? "●" : "○";
+		const indent = textWidth(mark) + 1;
+		// the whole option is drawn: what is sent is what the user could read. A long one wraps under its first word.
+		const lines = wrapText(label, Math.max(4, width - indent), role);
+		const y = rows.length;
+		lines.forEach((l, k) => rows.push(k === 0 ? [...textCells(mark, role), cell(" ", role), ...l] : [...Array.from({ length: indent }, () => cell(" ")), ...l]));
+		if (!locked) targets.push({ id: `choice:${path}:${index}`, kind: "choice", rect: { x: 0, y, w: width, h: lines.length }, label, choice: { of: c, index } });
+	};
+	c.options.forEach((o, i) => row(!!ans?.picks.includes(i), o, i));
+	if (c.other) {
+		const typed = ans?.other ? cleanOther(ans.text) : "";
+		row(typed !== "", "Other...", "other");
+		if (typed) {
+			const room = Math.max(4, width - 4);
+			const lines = wrapText(typed.replace(/\n/g, " ¶ "), room, "choice.other");
+			const shown = lines.slice(0, 2);
+			if (lines.length > 2) shown[1] = textCells(truncateText(shown[1].map((x) => x.ch).join("") + "…", room), "choice.other");
+			for (const l of shown) rows.push([cell(" "), cell(" "), cell(" "), cell(" "), ...l]);
+		}
+	}
+	return fromRows(width, rows, targets);
+}
+
+/**
+ * The bar under a widget that has Choices: how many are answered, and the buttons. Send carries the finished message, and has a
+ * target only when something is answered; Clear only when something is staged. After Send the bar only says so.
+ */
+export function answerBar(choices: Choice[], state: WState, title: string, width: number): Block {
+	if (state.sent) return fromRows(width, [state.sending ? textCells("Sending to the agent…", "text.muted") : textCells("Sent to the agent.", "choice.sent")]);
+	const { answered, total } = progress(choices, state.answers);
+	const staged = Object.values(state.answers).some((a) => a.picks.length > 0 || a.other);
+	const count = textCells(`${answered} of ${total} answered`, "text.muted");
+	const sendW = textWidth(SEND);
+	const clearW = textWidth(CLEAR);
+	const send = textCells(SEND, answered > 0 ? "btn" : "choice.locked");
+	const clear = textCells(CLEAR, staged ? "btn" : "choice.locked");
+	const gap = [cell(" "), cell(" ")];
+	// as much as fits on one row: the count and both buttons, else the count above the buttons, else one button per row
+	const rows: Cell[][] = [];
+	let sendAt: { x: number; y: number };
+	let clearAt: { x: number; y: number };
+	if (count.length + 2 + sendW + 2 + clearW <= width) {
+		rows.push([...count, ...gap, ...send, ...gap, ...clear]);
+		sendAt = { x: count.length + 2, y: 0 };
+		clearAt = { x: count.length + 2 + sendW + 2, y: 0 };
+	} else if (sendW + 2 + clearW <= width) {
+		rows.push(count, [...send, ...gap, ...clear]);
+		sendAt = { x: 0, y: 1 };
+		clearAt = { x: sendW + 2, y: 1 };
 	} else {
-		optCells.forEach((o, k) => {
-			targets.push({ id: `choice:${path}:${o.i}`, kind: "choice", rect: { x: 0, y: baseY + k, w: o.cells.length, h: 1 }, label: opts[o.i], send: `${q} — ${opts[o.i]}` });
-			lines.push(o.cells);
-		});
+		rows.push(count, send, clear);
+		sendAt = { x: 0, y: 1 };
+		clearAt = { x: 0, y: 2 };
 	}
-	return fromRows(width, [...head, ...hint, ...lines], targets);
+	const targets: Target[] = [];
+	if (answered > 0) targets.push({ id: "send", kind: "send", rect: { ...sendAt, w: sendW, h: 1 }, label: "Send answers", bar: { choices, title } });
+	if (staged) targets.push({ id: "clear", kind: "clear", rect: { ...clearAt, w: clearW, h: 1 }, label: "Clear" });
+	return fromRows(width, rows, targets);
 }
 
 export function tabs(el: El, width: number, ctx: Ctx, path: string): Block {
 	const items: El[] = el.props.items ?? [];
 	if (!items.length) return blank(width, 0);
 	const sel = Math.min(Math.max(0, ctx.state.tab[path] ?? 0), items.length - 1);
-	let labels = items.map((it) => truncateText(String(it.props.label ?? ""), 22));
-	const need = () => labels.reduce((a, l) => a + textWidth(l) + 4, 0);
-	let cap = 22;
-	while (need() > width && cap > 4) labels = items.map((it) => truncateText(String(it.props.label ?? ""), --cap));
-	const l0: ReturnType<typeof textCells> = [];
-	const l1: typeof l0 = [];
-	const l2: typeof l0 = [];
-	const targets: Target[] = [];
+	// Labels are never shortened to make the bar fit (a label wider than the whole pane is the one exception). A bar that does not
+	// fit wraps onto more rows, each a little tab bar of its own.
+	const labels = items.map((it) => truncateText(String(it.props.label ?? ""), Math.max(1, width - 4)));
+	const lines: number[][] = [];
+	let cur: number[] = [];
+	let used = 0;
 	labels.forEach((lab, i) => {
-		const iw = textWidth(lab) + 2;
-		const on = i === sel;
-		const role = on ? "tab.on" : "tab.off";
-		const x0 = l1.length;
-		if (on) {
-			l0.push(cell("╭", role), ...Array.from({ length: iw }, () => cell("─", role)), cell("╮", role));
-			l1.push(cell("│", role), cell(" ", role), ...textCells(lab, "tab.label"), cell(" ", role), cell("│", role));
-			l2.push(cell("╯", role), ...Array.from({ length: iw }, () => cell(" ")), cell("╰", role));
-		} else {
-			l0.push(...Array.from({ length: iw + 2 }, () => cell(" ")));
-			l1.push(cell(" "), cell(" "), ...textCells(lab, role), cell(" "), cell(" "));
-			l2.push(...Array.from({ length: iw + 2 }, () => cell("─", "tab.rule")));
+		const w = textWidth(lab) + 4;
+		if (cur.length && used + w > width) {
+			lines.push(cur);
+			cur = [];
+			used = 0;
 		}
-		targets.push({ id: `tab:${path}:${i}`, kind: "tab", rect: { x: x0, y: 1, w: iw + 2, h: 1 }, label: String(items[i].props.label ?? "") });
+		used += w;
+		cur.push(i);
 	});
-	while (l2.length < width) l2.push(cell("─", "tab.rule"));
-	const strip = fromRows(width, [l0, l1, l2], targets);
+	if (cur.length) lines.push(cur);
+	const rows: Cell[][] = [];
+	const targets: Target[] = [];
+	lines.forEach((idxs, k) => {
+		const l0: ReturnType<typeof textCells> = [];
+		const l1: typeof l0 = [];
+		const l2: typeof l0 = [];
+		idxs.forEach((i) => {
+			const lab = labels[i];
+			const iw = textWidth(lab) + 2;
+			const on = i === sel;
+			const role = on ? "tab.on" : "tab.off";
+			const x0 = l1.length;
+			if (on) {
+				l0.push(cell("╭", role), ...Array.from({ length: iw }, () => cell("─", role)), cell("╮", role));
+				l1.push(cell("│", role), cell(" ", role), ...textCells(lab, "tab.label"), cell(" ", role), cell("│", role));
+				l2.push(cell("╯", role), ...Array.from({ length: iw }, () => cell(" ")), cell("╰", role));
+			} else {
+				l0.push(...Array.from({ length: iw + 2 }, () => cell(" ")));
+				l1.push(cell(" "), cell(" "), ...textCells(lab, role), cell(" "), cell(" "));
+				l2.push(...Array.from({ length: iw + 2 }, () => cell("─", "tab.rule")));
+			}
+			targets.push({ id: `tab:${path}:${i}`, kind: "tab", rect: { x: x0, y: 3 * k + 1, w: iw + 2, h: 1 }, label: String(items[i].props.label ?? "") });
+		});
+		while (l2.length < width) l2.push(cell("─", "tab.rule"));
+		rows.push(l0, l1, l2);
+	});
+	const strip = fromRows(width, rows, targets);
 	ctx.tabs.push(String(items[sel].props.label ?? ""));
 	let content: Block;
 	try {
@@ -226,6 +292,16 @@ export function image(el: El, width: number, path: string, ctx: Ctx): { block: B
 	if (placed) {
 		// the picture is drawn over these cells by the host; here they are reserved, framed and clickable
 		const area = blank(placed.cols, placed.rows);
+		// The terminal draws the picture over these cells, so what is written here is only ever seen when it does not: a phone app that
+		// reports no cell size, a second client attached, a terminal without graphics. An empty box looks broken; this says what it is.
+		const say = (y: number, text: string) => {
+			if (y < 0 || y >= placed.rows || placed.cols < 8) return;
+			const cells = textCells(truncateText(text, placed.cols - 2), "text.muted");
+			area.rows[y] = padRow([...Array.from({ length: Math.max(0, Math.floor((placed.cols - cells.length) / 2)) }, () => cell(" ")), ...cells], placed.cols);
+		};
+		const mid = Math.floor((placed.rows - 1) / 2);
+		say(placed.rows >= 4 ? mid - 1 : mid, svc ? svc.describe(src) : name);
+		if (placed.rows >= 4) say(mid + 1, "no picture? terminal can't show it");
 		area.targets.push({ id: `image:${path}`, kind: "image", rect: { x: 0, y: 0, w: placed.cols, h: placed.rows }, label: `${alt}`, image: { key: placed.key, cols: placed.cols, rows: placed.rows } });
 		const cap = p.caption ? fromRows(placed.cols, wrapText(String(p.caption), placed.cols, "text.muted")) : null;
 		block = boxed(cap ? vstack([area, cap], 0, placed.cols) : area, { role: "image.border", title: alt, titleRole: "image.alt", padX: 0 });
@@ -252,6 +328,10 @@ export interface Anchor {
 	badgeForce?: boolean;
 	/** cells besides `rect` that belong to the element (a pie wedge) */
 	cells?: Array<[number, number]>;
+	/** a cell that was cut to fit: its whole text, readable in a panel (no tooltip needed) */
+	full?: string;
+	/** what to call the element in the hover line and the panel's title, when its tooltip key (`cell:3.Notes`) would read badly */
+	label?: string;
 }
 
 /** The mark that says "this element has a tooltip". Present in the user's font (JetBrains Mono), unlike the circled i. */
@@ -295,6 +375,11 @@ export function tipPanel(label: string, tip: Tip, width: number): Block {
 	if (tip.detail) parts.push(markdownBlock(tip.detail, iw));
 	if (tip.code) parts.push(codeInner(tip.code, tip.language, iw));
 	if (tip.link) parts.push(fromRows(iw, [textCells(truncateText(`↗ ${tip.linkLabel ?? tip.link}${tip.linkLabel ? ` — ${tip.link}` : ""}`, iw), "md.link")]));
+	if (tip.full !== undefined) {
+		// plain text, as it was written: not Markdown, and wrapped rather than cut
+		const body = wrapText(tip.full, iw, "");
+		parts.push(parts.length ? vstack([fromRows(iw, [textCells("the whole cell", "tip.hint")]), fromRows(iw, body)], 0, iw) : fromRows(iw, body));
+	}
 	const inner = vstack(parts.length ? parts : [fromRows(iw, [textCells(label, "tip.hint")])], 1, iw);
 	return boxed(inner, { role: `tip.${tip.tone ?? "info"}`, title: label });
 }
@@ -320,8 +405,9 @@ export function addWholeItem(el: El, block: Block, path: string, ctx: Ctx): void
 export function withTips(el: El, block: Block, anchors: Map<string, Anchor>, path: string, ctx: Ctx, avail = block.w): Block {
 	registerItems(el, block, anchors, path, ctx);
 	const tips: El[] = el.props.tooltips ?? [];
-	if (!tips.length) return block;
 	let panel: Block | null = null;
+	const panelWidth = () => Math.min(Math.max(avail, 20), Math.max(block.w, 44));
+	const tipped = new Set<string>();
 	for (const t of tips) {
 		const key = String(t.props.target ?? "");
 		const a = anchors.get(key);
@@ -329,13 +415,22 @@ export function withTips(el: El, block: Block, anchors: Map<string, Anchor>, pat
 			ctx.warnings.push(`${el.type}: tooltip target "${key}" does not match anything in the component`);
 			continue;
 		}
-		const tip: Tip = { hint: t.props.hint, detail: t.props.detail, code: t.props.code, language: t.props.language, tone: t.props.tone, link: t.props.link, linkLabel: t.props.linkLabel };
+		tipped.add(key);
+		const tip: Tip = { hint: t.props.hint, detail: t.props.detail, code: t.props.code, language: t.props.language, tone: t.props.tone, link: t.props.link, linkLabel: t.props.linkLabel, ...(a.full !== undefined ? { full: a.full } : {}) };
 		const existing = a.targetId ? block.targets.find((x) => x.id === a.targetId) : undefined;
 		const id = existing ? existing.id : `tip:${path}:${key}`;
 		if (existing) existing.tip = tip;
 		else block.targets.push({ id, kind: "tip", rect: a.rect, label: key, tip, ...(a.cells ? { cells: a.cells } : {}) });
 		placeBadge(block, a, tip.tone ?? "info");
-		if (ctx.state.tip === id && (tip.detail || tip.code || tip.link)) panel = tipPanel(key, tip, Math.min(Math.max(avail, 20), Math.max(block.w, 44)));
+		if (ctx.state.tip === id && (tip.detail || tip.code || tip.link || tip.full !== undefined)) panel = tipPanel(key, tip, panelWidth());
+	}
+	// a cell that was cut to fit and has no tooltip of its own: a tap reads it whole (no badge: the ellipsis is the cue)
+	for (const [key, a] of anchors) {
+		if (a.full === undefined || tipped.has(key)) continue;
+		const id = `tip:${path}:${key}`;
+		const tip: Tip = { full: a.full };
+		block.targets.push({ id, kind: "tip", rect: a.rect, label: a.label ?? key, tip });
+		if (ctx.state.tip === id) panel = tipPanel(a.label ?? key, tip, panelWidth());
 	}
 	return panel ? vstack([block, panel], 0, Math.max(block.w, panel.w)) : block;
 }

package/src/blocks/diagrams.ts

@@ -7,25 +7,9 @@ import type { DiagramResult } from "../diagram/layeredDiagram.ts";
 import type { El } from "../lang/library.ts";
 import type { Anchor } from "./core.ts";
 import type { Block, Ctx, Target } from "./types.ts";
+import { panBlock } from "./panblock.ts";
 import { cell, fromRows, padRow, textCells, vstack } from "./util.ts";
 
-/** Crop a block wider than `width` to a window starting at the saved pan offset. */
-export function panBlock(inner: Block, width: number, key: string, ctx: Ctx): Block {
-	if (inner.w <= width) return inner;
-	const maxPan = inner.w - width;
-	const pan = Math.min(maxPan, Math.max(0, ctx.state.pan[key] ?? 0));
-	ctx.state.pan[key] = pan;
-	const rows = inner.rows.map((r) => {
-		const seg = padRow(r, inner.w).slice(pan, pan + width);
-		if (seg.length && seg[0].ch === "") seg[0] = cell(" ");
-		if (seg.length && pan + width < inner.w && seg[seg.length - 1].ch !== "" && r[pan + width]?.ch === "") seg[seg.length - 1] = cell(" ");
-		return seg;
-	});
-	const targets: Target[] = inner.targets.map((t) => ({ ...t, rect: { ...t.rect, x: t.rect.x - pan }, pan: { key, x: t.rect.x, w: t.rect.w, view: width, total: inner.w } }));
-	const hint = textCells(`${pan > 0 ? "‹" : " "} columns ${pan + 1}–${pan + width} of ${inner.w} ${pan < maxPan ? "›" : " "}  select a node to pan`, "text.muted");
-	return { w: width, rows: [...rows, padRow(hint, width)], targets };
-}
-
 /**
  * A diagram's layout depends only on the component and the width, but the widget lays out again for a note, a tab, a resize
  * or a late picture. Routing wires is the costly part, so each result is kept with its component (and dropped with it). Nothing
@@ -85,7 +69,7 @@ export function dagBlock(el: El, width: number, path: string, ctx: Ctx): { block
 	const dy = p.title ? 1 : 0;
 	for (const n of res.nodes) anchors.set(n.id, { rect: { ...n.rect, y: n.rect.y + dy }, targetId: `node:${path}:${n.id}` });
 	const block = panBlock(inner, width, `pan:${path}`, ctx);
-	remapAnchors(anchors, inner, block);
+	remapAnchors(anchors, inner, block, ctx.state.pan[`pan:${path}`] ?? 0);
 	return { block, anchors };
 }
 
@@ -105,7 +89,7 @@ export function erdBlock(el: El, width: number, path: string, ctx: Ctx): { block
 		});
 	}
 	const block = panBlock(inner, width, `pan:${path}`, ctx);
-	remapAnchors(anchors, inner, block);
+	remapAnchors(anchors, inner, block, ctx.state.pan[`pan:${path}`] ?? 0);
 	return { block, anchors };
 }
 
@@ -124,19 +108,17 @@ export function infraBlock(el: El, width: number, path: string, ctx: Ctx): { blo
 		if (c) anchors.set(`${e.from}>${e.to}`, { rect: { x: Math.max(0, c[0] - 1), y: c[1] + dy, w: Math.max(3, e.labelCells.length + 2), h: 1 } });
 	}
 	const block = panBlock(inner, width, `pan:${path}`, ctx);
-	remapAnchors(anchors, inner, block);
+	remapAnchors(anchors, inner, block, ctx.state.pan[`pan:${path}`] ?? 0);
 	return { block, anchors };
 }
 
-/** after panning, anchors must follow the targets they point at */
-function remapAnchors(anchors: Map<string, Anchor>, inner: Block, panned: Block) {
-	if (panned === inner) return;
-	const pan = panned.targets[0]?.pan;
-	const dx = pan ? pan.x - panned.targets[0].rect.x : 0;
+/** after panning by `dx`, anchors must follow the targets they point at */
+function remapAnchors(anchors: Map<string, Anchor>, inner: Block, panned: Block, dx: number) {
+	if (panned === inner || !dx) return;
 	for (const [, a] of anchors) {
 		a.rect = { ...a.rect, x: a.rect.x - dx };
 		if (a.badge) a.badge = [a.badge[0] - dx, a.badge[1]];
 	}
 }
 
-export { offsetAnchors, textWidth };
+export { offsetAnchors, panBlock, textWidth };

package/src/blocks/fallback.ts

@@ -0,0 +1,25 @@
+// What a widget shows when its source cannot be drawn again (a language change an old session was never migrated across, or a
+// source from a newer version than this extension). Never a blank: the reader gets the reason and the start of the source.
+// Pure: lines of plain text; the caller colours them.
+
+const SOURCE_LINES = 12;
+const WIDTH = 80;
+
+/** One short line of plain text: control and escape characters are what a stored source must never be allowed to send to a terminal. */
+const tidy = (s: string, max: number): string => {
+	const clean = s.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ");
+	return clean.length > max ? clean.slice(0, max - 1) + "…" : clean;
+};
+
+export function fallbackLines(source: string, errors: string[], lang: number): string[] {
+	const lines = [`This widget could not be drawn again (OpenUI Lang v${lang}).`];
+	if (errors.length) lines.push(`Why: ${tidy(errors[0], WIDTH)}`);
+	const text = String(source ?? "");
+	if (text.trim()) {
+		lines.push("The source it was drawn from:");
+		const all = text.split("\n");
+		for (const l of all.slice(0, SOURCE_LINES)) lines.push(`  ${tidy(l, WIDTH)}`);
+		if (all.length > SOURCE_LINES) lines.push(`  … ${all.length - SOURCE_LINES} more line${all.length - SOURCE_LINES === 1 ? "" : "s"}`);
+	}
+	return lines;
+}

package/src/blocks/gesture.ts

@@ -0,0 +1,112 @@
+// What a pointer does to a block that is wider than its pane. Events in, actions out: no terminal and no pi, so the cases that
+// matter (a sideways flick, a drag on the thumb, a tap after a flick) are tested with plain objects.
+//
+// Why a recognizer at all: pi-tui understands only the vertical wheel. A horizontal one (SGR buttons 66 and 67) reaches a
+// widget as a `press` with button "right" or "none" that is never released, and while pi believes that press is still down
+// it does not turn the next tap into a `click`. The recognizer pans on those presses, remembers that it saw one, and
+// recognises the next tap itself from its press and release. Everything else about taps stays with pi's `click`.
+import { panAreaAt, targetAt } from "./interact.ts";
+import { clampPan, panFromTrack } from "./pan.ts";
+import type { Block, Target } from "./types.ts";
+
+/** The fields of pi's mouse event that are used. Coordinates are local to the block. */
+export interface MouseIn {
+	type: string;
+	button: string;
+	x: number;
+	y: number;
+	shift: boolean;
+	alt: boolean;
+	wheelDelta?: number;
+}
+
+export type Action =
+	| { kind: "pan"; key: string; to: number; capture?: boolean }
+	| { kind: "tap"; x: number; y: number }
+	/** a click that was already handled as a tap */
+	| { kind: "swallow" }
+	| { kind: "none" };
+
+/** Columns for one notch of a wheel or one horizontal flick event. */
+export const WHEEL_COLUMNS = 3;
+
+const NONE: Action = { kind: "none" };
+const same = (a: { x: number; y: number } | null, x: number, y: number) => !!a && a.x === x && a.y === y;
+
+export class Recognizer {
+	/** pi has been sent a press that no release will match (a horizontal flick) */
+	stuck = false;
+	private pressAt: { x: number; y: number } | null = null;
+	private ignoreClickAt: { x: number; y: number } | null = null;
+	/** the track being dragged: where it is and what it scrolls */
+	private drag: { key: string; track: Target["rect"]; total: number; view: number } | null = null;
+
+	reset(): void {
+		this.stuck = false;
+		this.pressAt = null;
+		this.ignoreClickAt = null;
+		this.drag = null;
+	}
+
+	private shift(block: Block, pan: Record<string, number>, ev: MouseIn, columns: number): Action {
+		const sc = panAreaAt(block, ev.x, ev.y)?.scroll;
+		if (!sc) return NONE;
+		return { kind: "pan", key: sc.key, to: clampPan((pan[sc.key] ?? 0) + columns, sc.total, sc.view) };
+	}
+
+	feed(ev: MouseIn, block: Block, pan: Record<string, number>): Action {
+		switch (ev.type) {
+			case "press": {
+				if (ev.button === "none" || ev.button === "right") {
+					// a horizontal wheel: "none" is SGR 67 (right), "right" is SGR 66 (left)
+					const a = this.shift(block, pan, ev, ev.button === "none" ? WHEEL_COLUMNS : -WHEEL_COLUMNS);
+					if (a.kind !== "none") this.stuck = true;
+					return a;
+				}
+				this.ignoreClickAt = null; // a new gesture: the click that followed an earlier tap is long gone
+				if (ev.button !== "left") return NONE;
+				this.pressAt = { x: ev.x, y: ev.y };
+				const t = targetAt(block, ev.x, ev.y);
+				if (t?.kind === "pan" && t.scroll?.part === "track") {
+					this.drag = { key: t.scroll.key, track: t.rect, total: t.scroll.total, view: t.scroll.view };
+					return { kind: "pan", key: t.scroll.key, to: panFromTrack(ev.x, t.rect, t.scroll.total, t.scroll.view), capture: true };
+				}
+				return NONE;
+			}
+			case "drag": {
+				const d = this.drag;
+				if (!d || ev.button !== "left") return NONE;
+				return { kind: "pan", key: d.key, to: panFromTrack(ev.x, d.track, d.total, d.view), capture: true };
+			}
+			case "release": {
+				if (ev.button !== "left") return NONE;
+				this.drag = null;
+				const wasStuck = this.stuck;
+				const press = this.pressAt;
+				this.pressAt = null;
+				this.stuck = false; // pi has seen a release: whatever it was holding is let go
+				if (wasStuck && same(press, ev.x, ev.y)) {
+					this.ignoreClickAt = { x: ev.x, y: ev.y };
+					return { kind: "tap", x: ev.x, y: ev.y };
+				}
+				return NONE;
+			}
+			case "click": {
+				this.stuck = false; // pi sent a click: it is healthy
+				if (same(this.ignoreClickAt, ev.x, ev.y)) {
+					this.ignoreClickAt = null;
+					return { kind: "swallow" };
+				}
+				this.ignoreClickAt = null;
+				return NONE;
+			}
+			case "wheel": {
+				if (!ev.shift && !ev.alt) return NONE; // the plain wheel scrolls the transcript
+				const d = Math.sign(ev.wheelDelta ?? 0);
+				return d ? this.shift(block, pan, ev, d * WHEEL_COLUMNS) : NONE;
+			}
+			default:
+				return NONE;
+		}
+	}
+}