@neuroplastio/xterm-addon-hotty 0.1.0-next.2 → 0.1.0-next.4

package/README.md

@@ -183,6 +183,16 @@ runs programs for whoever connects.
   click where it began. A second finger ends it with `dragend` and no
   target, and nothing more is heard until every finger lifts. A long press,
   or Alt held at the touch, never drags. Any other touch pans as below.
+
+  An element that also has `data-steps="<x> [<y>]"` (whole numbers, 0 for
+  none along that axis) says where in it the pointer is: every event of a
+  drag of it carries `x` and `y`, the pointer's step along its border box
+  (`getBoundingClientRect`, as it is at each move), rounded to the nearest
+  and clamped to 0 and the count, wherever the pointer or the finger is.
+  A `drag` also goes out each time the step changes. The counts are read
+  when the drag starts; once the element has left the document, the step
+  stays as it last was, as it does in a `dragend` that ends a drag early.
+  The capabilities report `steps: true`.
 - **Presses** (SPEC §5.2, §9: `p=1` on `a=place`). Every primary press of a
   mouse or a pen in the window reports `press` on its pointerdown, before
   the drag and the focus it causes; a tap reports it on the mousedown the

package/dist/hotty-xterm.js

@@ -683,6 +683,21 @@ var Touch = class {
   }
 };
 
+// src/steps.ts
+function parseSteps(value) {
+  if (value === null) return null;
+  const words = value.trim().split(/\s+/);
+  if (words.length > 2 || !words.every((w) => /^[0-9]+$/.test(w))) return null;
+  const [x, y = 0] = words.map(Number);
+  if (!Number.isSafeInteger(x) || !Number.isSafeInteger(y) || x === 0 && y === 0) return null;
+  return [x, y];
+}
+function stepAt(offset, size, count) {
+  if (!(size > 0)) return 0;
+  const at = Math.min(Math.max(offset / size, 0), 1) * count;
+  return Math.min(Math.floor(at + 0.5), count);
+}
+
 // src/resolver.ts
 var DROP = /* @__PURE__ */ new Set(["script", "iframe", "frame", "frameset", "object", "embed", "applet", "base", "meta", "portal", "fencedframe"]);
 var DROP_ATTRS = /* @__PURE__ */ new Set(["srcdoc", "autofocus", "http-equiv", "ping", "nonce", "integrity"]);
@@ -2289,25 +2304,49 @@ var Surface = class {
     if (!id) return;
     const [c, r] = this.cellOf(e);
     const keys = keysOf(e);
-    this.drag = { pointer: e.pointerId, start: id, target: id, c, r, keys };
-    this.emit("dragstart", id, { c, r, keys });
+    const d = { pointer: e.pointerId, start: id, steps: stepsOf(start), target: id, c, r, keys, step: {} };
+    d.step = this.stepIn(d, e.clientX, e.clientY);
+    this.drag = d;
+    this.emit("dragstart", id, { c, r, keys, ...d.step });
     try {
       this.doc.documentElement.setPointerCapture(e.pointerId);
     } catch {
     }
   }
-  /** A move during a drag: an event each time its target changes, and
-   * while it has none, each time its cell does. */
+  /** A move during a drag (`moveDrag`). */
   onDragMove(e) {
     const d = this.drag;
     if (!d || e.pointerId !== d.pointer) return;
-    const [c, r] = this.cellOf(e);
-    const target = this.dragTarget(this.elementAt(e, c, r));
-    const keys = keysOf(e);
-    if (target !== d.target || target === "" && (c !== d.c || r !== d.r)) {
-      this.emit("drag", target, { c, r, keys });
+    this.moveDrag(d, e.clientX, e.clientY, keysOf(e));
+  }
+  /** The pointer or the finger of a drag moved to (x, y) of the document:
+   * an event each time its target changes, while it has none each time its
+   * cell does, and each time its step does (SPEC §9.1); one for a move that
+   * changes more than one. */
+  moveDrag(d, x, y, keys) {
+    const [c, r] = this.cellAt(x, y);
+    const target = this.dragTarget(this.elementAtPoint(x, y, c, r));
+    const step = this.stepIn(d, x, y);
+    if (target !== d.target || target === "" && (c !== d.c || r !== d.r) || step.x !== d.step.x || step.y !== d.step.y) {
+      this.emit("drag", target, { c, r, keys, ...step });
     }
-    Object.assign(d, { target, c, r, keys });
+    Object.assign(d, { target, c, r, keys, step });
+  }
+  /**
+   * Where (x, y) of the document is in the element a drag started on, in
+   * its steps (SPEC §9.1): measured against its border box where the user
+   * sees it now, wherever the point is, and as they last were once the
+   * element has left the document. None when it has no steps.
+   */
+  stepIn(d, x, y) {
+    const s = d.steps;
+    if (!s) return {};
+    if (!s.el.isConnected) return d.step;
+    const box = s.el.getBoundingClientRect();
+    const step = {};
+    if (s.x) step.x = stepAt(x - box.left, box.width, s.x);
+    if (s.y) step.y = stepAt(y - box.top, box.height, s.y);
+    return step;
   }
   /** The release ends the drag, wherever it is. Where it began, it is the
    * click it would have been without the drag; anywhere else, no click. */
@@ -2318,7 +2357,7 @@ var Surface = class {
     const [c, r] = this.cellOf(e);
     const at = this.elementAt(e, c, r);
     const target = this.dragTarget(at);
-    this.emit("dragend", target, { c, r, keys: keysOf(e) });
+    this.emit("dragend", target, { c, r, keys: keysOf(e), ...this.stepIn(d, e.clientX, e.clientY) });
     this.dragReleased = true;
     setTimeout(() => this.dragReleased = false, 0);
     if (target === d.start && at) this.reportClick(ancestry(at));
@@ -2331,13 +2370,13 @@ var Surface = class {
   /**
    * Ends a drag under way without a release (SPEC §9.1: its placement went
    * away, a new document came, or the pointer was lost): `dragend` with no
-   * target, at the last cell the program heard of.
+   * target, at the last cell and step the program heard of.
    */
   cancelDrag() {
     const d = this.drag;
     if (!d) return;
     this.dropDrag();
-    this.emit("dragend", "", { c: d.c, r: d.r, keys: d.keys });
+    this.emit("dragend", "", { c: d.c, r: d.r, keys: d.keys, ...d.step });
   }
   /** Ends a drag under way, silently (a detached or deleted surface). */
   dropDrag() {
@@ -2454,25 +2493,20 @@ var Surface = class {
     const [c, r] = this.cellAt(begin.x, begin.y);
     const keys = keysOf(begin);
     this.reportPress(e);
-    this.drag = { pointer: NaN, start: id, target: id, c, r, keys };
-    this.emit("dragstart", id, { c, r, keys });
+    const d = { pointer: NaN, start: id, steps: stepsOf(start), target: id, c, r, keys, step: {} };
+    d.step = this.stepIn(d, begin.x, begin.y);
+    this.drag = d;
+    this.emit("dragstart", id, { c, r, keys, ...d.step });
     this.pressAt(e);
     const t = [...e.changedTouches][0];
     if (t) this.touchDragMove(t.clientX, t.clientY, e);
     return true;
   }
   /** A touch drag's finger moved to (x, y) of the document: as a pointer's
-   * move (`onDragMove`). */
+   * move (`moveDrag`). */
   touchDragMove(x, y, e) {
     const d = this.drag;
-    if (!d) return;
-    const [c, r] = this.cellAt(x, y);
-    const target = this.dragTarget(this.elementAtPoint(x, y, c, r));
-    const keys = keysOf(e);
-    if (target !== d.target || target === "" && (c !== d.c || r !== d.r)) {
-      this.emit("drag", target, { c, r, keys });
-    }
-    Object.assign(d, { target, c, r, keys });
+    if (d) this.moveDrag(d, x, y, keysOf(e));
   }
   /** A touch drag's finger lifted at (x, y): as a pointer's release
    * (`onDragUp`), a click where it began. */
@@ -2483,7 +2517,7 @@ var Surface = class {
     const [c, r] = this.cellAt(x, y);
     const at = this.elementAtPoint(x, y, c, r);
     const target = this.dragTarget(at);
-    this.emit("dragend", target, { c, r, keys: keysOf(e) });
+    this.emit("dragend", target, { c, r, keys: keysOf(e), ...this.stepIn(d, x, y) });
     this.dragReleased = true;
     setTimeout(() => this.dragReleased = false, 0);
     if (target === d.start && at) this.reportClick(ancestry(at));
@@ -2573,17 +2607,21 @@ var Surface = class {
   /**
    * The cells an element's border box covers as the user sees it, scrolled
    * included (SPEC §9: `area`), counted from the surface's top left cell:
-   * whole, where it is clipped or scrolled away. An edge within half a
-   * device pixel of a cell's is on it: layout rounds positions to fractions
-   * of a pixel, and the user sees no less than a device pixel.
+   * whole, where it is clipped or scrolled away. An edge close enough to a
+   * cell's is on it: within half a device pixel, which the user cannot see,
+   * plus what layout loses on the way there. Layout keeps lengths in fixed
+   * units (1/64 px in Chromium, 1/60 in Firefox) and cuts each box's to
+   * them, so with a cell a fraction of a pixel, a row 29 boxes of one cell
+   * down starts up to 29/64 px short of its cell.
    */
   areaOf(el) {
     const b = el.getBoundingClientRect();
-    const tol = 0.5 / (this.frame.ownerDocument.defaultView?.devicePixelRatio || 1);
-    const c = Math.floor((b.left + tol) / this.cellW);
-    const r = Math.floor((b.top + tol) / this.cellH);
-    const right = Math.ceil((b.right - tol) / this.cellW);
-    const bottom = Math.ceil((b.bottom - tol) / this.cellH);
+    const half = 0.5 / (this.frame.ownerDocument.defaultView?.devicePixelRatio || 1);
+    const slack = (edge, cell) => half + Math.abs(edge / cell) / 60;
+    const c = Math.floor((b.left + slack(b.left, this.cellW)) / this.cellW);
+    const r = Math.floor((b.top + slack(b.top, this.cellH)) / this.cellH);
+    const right = Math.ceil((b.right - slack(b.right, this.cellW)) / this.cellW);
+    const bottom = Math.ceil((b.bottom - slack(b.bottom, this.cellH)) / this.cellH);
     return { c, r, w: Math.max(0, right - c), h: Math.max(0, bottom - r) };
   }
   // --- Events for the program (PROTOCOL §8) --------------------------------
@@ -2973,6 +3011,10 @@ function isElement(n) {
 function listens(el, what) {
   return (el.getAttribute("data-on") ?? "").split(/\s+/).includes(what);
 }
+function stepsOf(el) {
+  const n = parseSteps(el.getAttribute("data-steps"));
+  return n && { el, x: n[0], y: n[1] };
+}
 function ancestry(el) {
   const out = [];
   for (let n = el; n; n = n.parentElement) out.push(n);
@@ -3280,6 +3322,9 @@ var HottyAddon = class {
   css = "";
   policy;
   metrics = { cellW: 0, cellH: 0, key: "" };
+  /** The cell (CSS px) and font the program last heard of, or saw at the
+   * start: a `resize` is owed when both have changed since (SPEC §5.3). */
+  told = { cellW: 0, cellH: 0, font: "" };
   resizeTimer = null;
   /** A surface's key is being forwarded to the terminal (`key`), and the
    * terminal's own focus is held off meanwhile. A program in the page may
@@ -3516,6 +3561,7 @@ var HottyAddon = class {
       limits: { resources: this.store.quota, surfaces: this.opts.maxSurfaces },
       net: this.policy,
       scroll: true,
+      steps: true,
       host: HOST,
       version: VERSION
     };
@@ -3933,23 +3979,40 @@ var HottyAddon = class {
     const o = this.term.options;
     const key = `${cellW}x${cellH}|${o.fontFamily}|${o.fontSize}|${JSON.stringify(o.theme ?? {})}`;
     if (key === this.metrics.key) return;
-    const sizeChanged = this.metrics.cellW !== 0 && (cellW !== this.metrics.cellW || cellH !== this.metrics.cellH);
+    const first = this.metrics.cellW === 0;
     this.metrics = { cellW, cellH, key };
+    if (first) this.told = { cellW, cellH, font: this.font() };
+    else this.settle();
     if (this.surfaces.size === 0) return;
     const css = this.hostCss();
     const scheme = this.scheme();
     for (const s of this.surfaces.values()) s.setHostCss(css, scheme);
     this.reposition();
-    if (sizeChanged) {
-      if (this.resizeTimer) clearTimeout(this.resizeTimer);
-      this.resizeTimer = setTimeout(() => {
-        for (const p of this.placements.values()) {
-          const s = p.surface;
-          if (s.detached) continue;
-          this.host().event(s.name, "resize", "", { w: Math.round(s.cols * cellW), h: s.rows * cellH });
-        }
-      }, 100);
-    }
+  }
+  font() {
+    return `${this.term.options.fontFamily}|${this.term.options.fontSize}`;
+  }
+  /** Once the cell and font settle: a new font that changed the cell is
+   * re-rendered with no program involvement, so the program hears its new
+   * size (SPEC §5.3, §9). A browser's zoom moves the cell only by device
+   * pixel rounding and keeps the font, and is not told. xterm.js may take
+   * the font and its cell in two renders, so this waits for both. */
+  settle() {
+    if (this.resizeTimer) clearTimeout(this.resizeTimer);
+    this.resizeTimer = setTimeout(() => {
+      this.resizeTimer = null;
+      const { cellW, cellH } = this.cell();
+      const font = this.font();
+      const t = this.told;
+      const owed = font !== t.font && (cellW !== t.cellW || cellH !== t.cellH);
+      this.told = { cellW, cellH, font };
+      if (!owed) return;
+      for (const p of this.placements.values()) {
+        const s = p.surface;
+        if (s.detached) continue;
+        this.host().event(s.name, "resize", "", { w: Math.round(s.cols * cellW), h: s.rows * cellH });
+      }
+    }, 100);
   }
 };
 function sequence(chain, f) {