tosijs-styled-editor 0.5.2 → 0.6.0

package/dist/selection.d.ts

@@ -36,7 +36,23 @@
  * comma in `hello,` takes the comma and stopping inside `hello` does not —
  * "as necessary" falls out rather than needing a rule.
  */
-export declare function stickySelectionBounds(text: string, anchor: number, head: number): {
+export declare function stickySelectionBounds(text: string, anchor: number, head: number, 
+/**
+ * Has the drag left the word it began in? Defaults to asking in LOGICAL
+ * offsets, which is right whenever visual and logical order agree.
+ *
+ * They do not agree inside a bidi run, and that made short runs unselectable
+ * by drag. `עברית` inside an English list item is ~43px wide and renders
+ * right-to-left, so moving the pointer a few pixels RIGHT walks logically
+ * BACKWARDS out of the word — the offset test says "left the word", both ends
+ * snap, and the whole run highlights as one block on the first small
+ * movement. The same gesture in English stays inside a word long enough to
+ * show character precision, which is why only RTL looked broken.
+ *
+ * The caller measures it against the word's rendered box instead. Same rule,
+ * asked in the space the user is actually moving through.
+ */
+leftTheAnchorWord?: boolean): {
     start: number;
     end: number;
 };
@@ -54,6 +70,35 @@ export declare class Selectable {
     root: HTMLElement;
     selecting: number | false;
     touchMode: boolean;
+    /**
+     * When word stickiness applies.
+     *
+     * `'touch'` by default, because the two pointers want different things. A
+     * mouse user expects the platform's own behaviour — character precision, and
+     * a double-click when they want a word — and silently rounding their drag out
+     * to word boundaries is the editor overriding a gesture they aimed. A
+     * fingertip has no such precision to override: snapping is the only way a
+     * drag across a word ends up selecting that word.
+     *
+     * `'always'` restores stickiness for the mouse too, `'never'` turns it off
+     * entirely. Read through `stickyApplies`, which also knows which pointer is
+     * mid-gesture.
+     *
+     * HYBRID DEVICES (a Surface Pro, a touchscreen laptop) are the reason this is
+     * decided per gesture rather than once per device. Two things make that hold:
+     * `touchMode` flips on every `mousedown`/`touchstart`, and the touch
+     * listeners are registered `passive: false` so `handleTouchStart` can
+     * `preventDefault()` — which is what stops Chrome firing its COMPATIBILITY
+     * mouse events after a touch. Without that, a finger would raise
+     * `touchstart` (sticky) and then a synthetic `mousedown` (not sticky) and
+     * lose stickiness mid-drag. Do not make those listeners passive.
+     *
+     * A stylus is a MOUSE here: pen input arrives as pointer + compatibility
+     * mouse events, not touch events, so a Surface Pen gets character precision.
+     * That is the right answer for a precise instrument, but it is a consequence
+     * of how the events arrive rather than a decision taken anywhere.
+     */
+    stickySelection: 'touch' | 'always' | 'never';
     constructor(root: HTMLElement);
     private lastHovered;
     /** A click inside a selection, resolved on mouseup if no drag started */
@@ -85,6 +130,44 @@ export declare class Selectable {
         } | null;
         indexOf: (node: Text, offset: number) => number | null;
     };
+    /**
+     * Remember where a character-granularity drag began, so the move handler can
+     * tell whether the pointer has left the anchor word yet.
+     *
+     * The mouse and the touch path BOTH call this. They used not to: the anchor
+     * was assigned inline in `handleMouseDown`, `handleTouchStart` was written
+     * separately, and so word stickiness existed for the mouse and not for the
+     * finger — exactly backwards, since a fingertip is the imprecise pointer.
+     */
+    private setDragAnchor;
+    /**
+     * Extend a live drag to a point: word-sticky where that applies, otherwise
+     * the end bound alone.
+     *
+     * Shared by the mouse and touch move handlers. Keeping two copies of this is
+     * how touch ended up without stickiness, under a comment claiming it was the
+     * "same measurement as a mouse drag" — true of `characterAtPoint`, false of
+     * the sticky rule, and the comment is what made it look finished.
+     */
+    extendTo(x: number, y: number, which?: 'start' | 'end'): void;
+    /**
+     * Begin dragging ONE existing bound, with the OTHER bound as the anchor —
+     * what a touch affordance handle does.
+     *
+     * This exists so a handle drag is the SAME gesture as a drag across text, and
+     * therefore gets the same stickiness. The component used to re-implement
+     * "move a bound to the character under the pointer" itself, which made it a
+     * third copy of the rule: once `Selectable`'s mouse and touch paths were
+     * sharing, the handles were the remaining path still doing it the old way, so
+     * a phone — where handles ARE how you adjust a selection — saw no snapping no
+     * matter what the two paths in here did.
+     *
+     * `touchMode` is set because a handle only exists as a result of touch, and
+     * `stickySelection: 'touch'` has to answer true for it.
+     */
+    beginBoundDrag(which: 'start' | 'end'): void;
+    /** End a handle drag, clearing the anchor as mouseup and touchend do. */
+    endBoundDrag(): void;
     /**
      * Move BOTH bounds, snapped to word boundaries once the drag has left the
      * word it started in. Returns false when stickiness does not apply and the
@@ -95,6 +178,26 @@ export declare class Selectable {
      * falls back — the text index is per-block, and a selection spanning blocks
      * has bigger units than words anyway.
      */
+    /**
+     * Is the pointer still inside the rendered box of the word the drag began in?
+     *
+     * Measured per LINE BOX (`getClientRects()`), not as one union rect: a word
+     * that wraps has two boxes with a huge gap between them, and the union would
+     * call the whole intervening area "inside the word".
+     *
+     * This is the visual half of the sticky rule. Asking it in logical offsets
+     * instead is what made a short right-to-left run snap as a single block on
+     * the first few pixels of movement — see `stickySelectionBounds`.
+     */
+    private pointerInAnchorWord;
+    /**
+     * Does word stickiness apply to the gesture in progress?
+     *
+     * `touchMode` is per-gesture — false on mousedown, true on touchstart — so
+     * one editor answers differently for a finger and for a mouse, which is the
+     * point: a hybrid laptop is one document with two pointers.
+     */
+    private get stickyApplies();
     private extendSticky;
     /** Put the bounds around the word containing an offset in a text node. */
     selectWordAt(node: Text, offset: number): void;

package/dist/tosijs-styled-editor.d.ts

@@ -11,6 +11,27 @@ interface EditableParts extends PartsMap {
     edgeStart: HTMLElement;
     edgeEnd: HTMLElement;
 }
+/**
+ * Edge length of a touch affordance, in px. Referenced by the CSS that sizes
+ * them AND by the maths that places them — they were two independent 44s, and
+ * the placement maths is where that drifts silently.
+ */
+export declare const AFFORDANCE_SIZE = 44;
+/**
+ * Where the context-menu affordance goes, horizontally, in doc coordinates.
+ *
+ * The start handle occupies `[startX - size, startX]` on the SAME row as the
+ * menu (both sit a handle's height above the first line), so a menu centred on
+ * the selection overlaps it whenever the selection is narrower than one
+ * handle — which is most selections, since 44px is only a few characters at any
+ * normal size. Reported from an iPhone.
+ *
+ * So: centred when there is room, otherwise forced right of the start handle,
+ * otherwise left of it. The collapsed-caret case already placed the menu at
+ * exactly `startX`, which is this rule's floor — so both cases go through here
+ * now rather than one of them being right by hand.
+ */
+export declare function menuAffordanceX(startX: number, endX: number, size: number, maxX: number): number;
 export declare class TosijsStyledEditor extends WebComponent<EditableParts> {
     static formAssociated: boolean;
     static preferredTagName: string;
@@ -110,6 +131,69 @@ export declare class TosijsStyledEditor extends WebComponent<EditableParts> {
      * new line, a new session.
      */
     trackChanges: boolean;
+    /**
+     * Record a cross-block merge as *blocks out, blocks in* instead of refusing
+     * it. **OFF in 0.6.0, and that is a release decision rather than a default.**
+     *
+     * The representation is sound and the primitive is tested, but RESOLUTION has
+     * a confirmed defect: `trackStructuralEdit` asks `trackDeletion` to strike
+     * each outgoing block, `trackDeletion` silently declines any block with
+     * nothing to mark (empty, inline-wrapper-only, or already fully struck), and
+     * nothing reconciles the decline — so accepting such a merge leaves that
+     * block standing and anchors the replacement after it:
+     *
+     *     <p>First</p><p></p><p>Third</p>  + Delete in the empty block
+     *       tracking off          → <p>First|</p><p>Third</p>
+     *       tracking on, accepted → <p></p><p>First|</p><p>Third</p>
+     *
+     * A flag about REVIEW deciding document structure is the one class this
+     * release spent five correctness rounds eliminating, so the feature waits for
+     * 0.7.0 rather than shipping reachable (board #3107). `rejectChanges()` is
+     * correct; accept is the broken half.
+     *
+     * With it off, a cross-block merge is REFUSED while tracking — `0.5.x`'s
+     * behaviour — through `merge-blocks-backward`, `merge-blocks-forward` and
+     * `merge-blocks-selection`. Unlike 0.5.x those refusals are not overridable,
+     * for the same reason `merge-blocks-not-mergeable` is not: an override that
+     * half-applies a gesture is what three earlier rounds kept producing.
+     *
+     * Turning it on is supported for working ON the feature. It is not a
+     * supported configuration for a document you care about.
+     */
+    trackStructuralEdits: boolean;
+    /**
+     * When a drag selection snaps to word boundaries: `'touch'` (the default),
+     * `'always'` or `'never'`.
+     *
+     * The default is per-pointer on purpose. A mouse user gets the platform's own
+     * behaviour — character precision, double-click for a word — because rounding
+     * a drag they aimed out to the nearest words is the editor overriding them. A
+     * fingertip has no precision to override, so snapping is what makes a drag
+     * across a word select that word. One editor answers differently for the two,
+     * which is what a hybrid laptop needs.
+     *
+     * A getter/setter over the `Selectable`'s own field, so it can be changed at
+     * any time and takes effect on the next drag — including before connection,
+     * which the creator form (`tosijsStyledEditor({ stickySelection: 'never' })`)
+     * relies on.
+     *
+     * It was a plain field assigned once in `connectedCallback`, which made every
+     * post-connection write silently inert while this comment promised otherwise
+     * — a host's "snap to words" preference toggle would have been a dead
+     * control. Nothing caught it because every test set
+     * `Selectable.stickySelection` directly, so deleting the one forwarding line
+     * left the suite green (`reviews/0.6.0-pre-release.md`, M-2).
+     */
+    get stickySelection(): 'touch' | 'always' | 'never';
+    set stickySelection(mode: 'touch' | 'always' | 'never');
+    /**
+     * Holds `stickySelection` until there is a `Selectable` to hold it.
+     *
+     * No default of its own: `Selectable` declares it, and two copies of one
+     * default is how they drift. Before connection the getter reads this, which
+     * starts as the same literal only because it is assigned from nowhere else.
+     */
+    private pendingStickySelection;
     /**
      * Identifies this editing session.
      *
@@ -204,25 +288,127 @@ export declare class TosijsStyledEditor extends WebComponent<EditableParts> {
      * `detail.reason` names which edit was refused.
      */
     /**
-     * Run a gesture with tracking suspended.
+     * Move the bounds markers out of a block that is about to be removed.
+     *
+     * A block proposed by a structural edit is pure proposal, so rejecting it
+     * MUST take the block — but the caret is sitting in it, and an editor with no
+     * insertion point silently swallows everything typed into it. So the caret
+     * moves to the end of the preceding block, which for a rejected merge is
+     * where the restored text now ends.
+     */
+    private rescueCaretFrom;
+    /**
+     * Is everything in this block already inside a `<tosi-del>`?
+     *
+     * Asked before striking a block, so a second pass does not nest a mark
+     * inside a mark. It has to look at CONTENT, not element children: the first
+     * version tested `firstElementChild.matches(DEL_TAG) && children.length === 1`
+     * and so answered "already deleted" for `<p>keep <tosi-del>cut</tosi-del></p>`
+     * — the text node is not an element child. The block was then skipped, its
+     * surviving text stayed put, and accepting the merge left that text in the
+     * document TWICE, once in the original and once in the replacement.
+     */
+    private isFullyStruck;
+    /**
+     * A block's content as it would read if MY pending changes were accepted.
+     *
+     * Cloned, so the original is untouched. Insertions become plain text and
+     * deletions really go, so the proposal reads as the document reads NOW —
+     * which is what a reviewer is being asked to compare against. Marks are not
+     * copied: a copy cannot carry a mark's identity, and the originals keep
+     * theirs and stay independently resolvable. Selection chrome is dropped: the
+     * caret is placed deliberately at the join afterwards, and a cloned marker
+     * would be a second caret.
+     */
+    private resolvedClone;
+    /**
+     * A block like `model`, without the selection state stuck to it.
+     *
+     * `.selected-block` / `.first-block` / `.last-block` describe a selection in
+     * flight, not the document, and copying them onto a newly proposed block
+     * makes it look selected to every subsequent query.
+     */
+    private blockLike;
+    /**
+     * Can this pair of blocks be merged into one block at all?
+     *
+     * A list is not a paragraph: merging `<ul>` with `<p>` produces loose text as
+     * a direct child of the list, and on a grid table the mark becomes a grid
+     * item and shifts every `cellIndex`. Reproduced before this guard existed:
+     * a Backspace joining a table and a paragraph accepted to a document with
+     * the paragraph's text *gone entirely*.
+     *
+     * v0.5.0 refused every cross-block merge, so replacing that blanket refusal
+     * with a tracked merge silently widened what the editor would attempt. The
+     * guard has to live on ALL THREE paths — both keystrokes and the selection —
+     * which is exactly the kind of "applied at one site, missed at five" shape
+     * this subsystem keeps producing.
+     */
+    private canMergeBlocks;
+    /**
+     * Record a structural edit the brute-force way: BLOCKS OUT, BLOCKS IN.
+     *
+     * `blocksOut` are struck whole (`data-block-delete`, so accepting removes
+     * them rather than leaving them empty) and one new block is proposed
+     * (`data-block-insert`). The gesture shares one `data-change`, so
+     * `acceptChanges(id)` / `rejectChanges(id)` resolve it together — one
+     * keystroke is one change, the same rule paste follows. That is NOT a claim
+     * that a merge is atomic with everything around it: marks already in these
+     * blocks keep their own ids.
+     *
+     * CALLERS must have asked `canMergeBlocks` FIRST — this records, it does not
+     * decide, and it does not veto. A merge is an ordinary edit: marks already in
+     * these blocks keep their own ids and stay independently resolvable, because
+     * privileging a structural edit over a textual one is not this feature's
+     * job. What the reviewer sees is the old text and the new text; what ends up
+     * in the document is their call.
+     *
+     * Returns the new mark and its caret; it always records something.
+     */
+    private trackStructuralEdit;
+    /**
+     * Announce a structural refusal, and report whether the host overrode it.
      *
-     * For the one case where a host has OVERRIDDEN a structural refusal. The
-     * edit then happens as a plain structural change with no marks — which is
-     * the only honest reading, since if tracking could have represented it there
-     * would have been nothing to refuse.
+     * `false` means a host called `preventDefault()`. Honoured for the POLICY
+     * refusals — `remove-list-item`, `merge-list-items` — where proceeding with
+     * the raw edit is a coherent thing to want.
      *
-     * Without this the override half-applied: the block merge itself went
-     * through a raw `caretBlock.remove()` with nothing in `changes`, while the
-     * character that rides along on the same keystroke was MARKED — leaving the
-     * document simultaneously mid-merge and mid-proposal, where neither
-     * accepting nor rejecting reproduces a document either party proposed.
+     * Not honoured for `merge-blocks-not-mergeable`, which goes through
+     * `refuseMerge`; there is no coherent override for a guard about valid DOM
+     * that fires with tracking off. There used to be an `asUntracked` helper for
+     * exactly that case, and it is gone with the contract it served: every one of
+     * its three call sites was either unreachable or performed a destructive
+     * no-op.
      */
-    private asUntracked;
     private refuseStructural;
+    /**
+     * Stamp a change mark as this editor, this session. One address, so the five
+     * that used to write these attributes by hand cannot drift again — and one of
+     * them already had (`reviews/0.6.0-dx-review.md`, M-3). The rule lives in
+     * `changes.ts`'s `stampMark`, beside the sanitizer it has to apply.
+     */
+    private stamp;
     /** Every tracked change, in document order. */
     get changes(): TrackedChange[];
     /** Accept one change by id, or every change when given none. */
     acceptChanges(id?: string): void;
+    /**
+     * The top-level blocks owned by the block-scoped marks among `targets`.
+     *
+     * ONE address for what was the same predicate at two — the accept sweep and
+     * the reject sweep — and both got it wrong the same way. They took
+     * `c.element.parentElement` and kept it only if its parent was the doc. For
+     * a NESTED mark that is the wrong element: a struck intermediate proposal is
+     * `<p><tosi-del data-block-delete><tosi-ins data-block-insert>…</tosi-ins></tosi-del></p>`,
+     * so the insert mark's parent is the `<tosi-del>`, the `<p>` was excluded
+     * from the sweep, and rejecting a chain of merges left one stray empty
+     * paragraph per intermediate step — in the document and in `value`
+     * (`reviews/0.6.0-remediation-rereview.md`, M-2).
+     *
+     * `block()` already walks to the top-level block, which is both the right
+     * answer and the condition the hand-written filter was approximating.
+     */
+    private blocksOwnedByMarks;
     /** Reject one change by id, or every change when given none. */
     rejectChanges(id?: string): void;
     /**
@@ -469,6 +655,96 @@ export declare class TosijsStyledEditor extends WebComponent<EditableParts> {
      * Returns the isolate in force, or null when none is needed.
      */
     private isolateForTyping;
+    /**
+     * Refuse a cross-block gesture whose blocks cannot become one block.
+     *
+     * ONE address, called from both keystroke paths. The previous version was a
+     * 17-line block meant to be pasted into each — and it went into `backspace()`
+     * TWICE and `forwardDelete()` not at all, so three Delete presses still
+     * destroyed a grid table in the untracked default while the commit message
+     * said both paths were covered. `grep -c` returned 2 and I read it as one per
+     * path; counting occurrences is not verifying placement.
+     *
+     * It gates the WHOLE gesture, not just the merge: with the check on the merge
+     * alone the character deletion ran first, so a refused merge still ate a
+     * character of the neighbouring block, unbounded, with no event to observe.
+     */
+    private refuseIfUnmergeable;
+    /**
+     * Announce an unmergeable-blocks refusal. **Not overridable**, and the
+     * dispatch result is deliberately discarded.
+     *
+     * `merge-blocks-not-mergeable` is the one refusal about VALID DOM rather than
+     * review policy — merging a list or a grid table puts loose text directly
+     * inside a `<ul>`, or turns a mark into a grid item and shifts every
+     * `cellIndex`. It fires with `trackChanges` OFF as well, where "perform it
+     * untracked" means nothing, which is what settles the question: there is no
+     * coherent thing for an override to do. The other refusals
+     * (`remove-list-item`, `merge-list-items`) are policy and stay overridable
+     * through `refuseStructural` directly.
+     *
+     * It was ACCIDENTALLY non-overridable before, which is worse than either
+     * answer: `refuseIfUnmergeable` discarded `refuseStructural`'s return and the
+     * only code that read it — an inner `canMergeBlocks` branch — had become
+     * unreachable, because by the time it ran the guard had already proved the
+     * pair mergeable. So a reader checking "is the override honoured?" found code
+     * that honoured it and never learned it could not run, while README promised
+     * `preventDefault()` performed the edit untracked
+     * (`reviews/0.6.0-pre-release.md`, M-1).
+     */
+    private refuseMerge;
+    /**
+     * Record a cross-block merge: both blocks out, one merged block in.
+     *
+     * `earlier` and `later` are in DOCUMENT order, which the callers have to fix
+     * because Backspace looks back and Delete looks forward. One address for the
+     * two keystroke paths: they each carried a copy of this, identical down to
+     * the comments and differing only in the order of that pair — and the
+     * previous generation of that same paste is what put a guard into
+     * `backspace()` twice and `forwardDelete()` not at all.
+     */
+    /**
+     * The UNTRACKED cross-block gesture: delete the paragraph break, and nothing
+     * else.
+     *
+     * "And nothing else" is the fix. Both keystroke paths used to delete a
+     * CHARACTER first and then merge, so `<p>one</p><p>two</p>` + Backspace at
+     * the start of `two` produced **"ontwo"** and Delete at the end of `one`
+     * produced **"onewo"** — silent content loss on the shipped default path with
+     * the commonest keystroke in a text editor. The tracked path was correct on
+     * the identical DOM, because it returns before the character deletion.
+     *
+     * The rule was already written down one comment above the bug: a deletion
+     * that crosses a block boundary deletes a paragraph BREAK, not a character.
+     * It had been applied to the REFUSED case (by hoisting `refuseIfUnmergeable`)
+     * and never to the allowed one. (`reviews/0.6.0-remediation-rereview.md`,
+     * B-1 — pre-existing, found in triage, covered by no test.)
+     *
+     * Element content follows the same rule: Backspace at the start of a
+     * paragraph whose predecessor ends in an `<img>` merges the paragraphs, it
+     * does not eat the image.
+     */
+    private mergeBlocksRaw;
+    /**
+     * Should this gesture be RECORDED structurally, or refused?
+     *
+     * One address, so the four dispatch sites cannot disagree — which is the
+     * failure this release spent five rounds on. `reason` is the 0.5.x refusal
+     * string for the gesture, so a host's existing handler keeps working.
+     */
+    private mayTrackStructurally;
+    private mergeBlocksTracked;
+    /**
+     * The nearest sibling block in `direction`, skipping this editor's own chrome.
+     *
+     * The affordance div is a sibling of every block, not a descendant of one, so
+     * a naive `previousElementSibling`/`nextElementSibling` finds UI furniture —
+     * and did: it parked the caret inside `.touch-affordances`, where
+     * `insertionPoint()` still answers non-null and the next keystroke builds
+     * text into chrome. Extracted from `rescueCaretFrom`, which had the only
+     * copy, before adding a second caller.
+     */
+    private siblingBlock;
     /** Delete the character before the caret */
     private backspace;
     /** Forward delete */

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.5.2";
+export declare const version = "0.6.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tosijs-styled-editor",
-  "version": "0.5.2",
-  "description": "Rich text editor web component \u2014 no contentEditable, no browser selection APIs",
+  "version": "0.6.0",
+  "description": "Rich text editor web component — no contentEditable, no browser selection APIs",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tonioloewald/tosijs-editor.git"
@@ -41,7 +41,16 @@
     "format": "bun prettier --write .",
     "haltija": "haltija --name tosijs-editor --port 8702 --server",
     "tls": "bunx tosijs-dev-certs",
-    "typecheck": "bun tsc --noEmit --noUnusedLocals --noUnusedParameters"
+    "typecheck": "bun tsc --noEmit --noUnusedLocals --noUnusedParameters",
+    "test:browser": "bun bin/test-browser.ts",
+    "dev:stop": "bun bin/dev-stop.ts",
+    "release:ready": "bun ../tosijs-coding-practices/tools/attest.ts",
+    "falsify": "bun bin/falsify.ts"
+  },
+  "releaseDoctor": {
+    "attestedLanes": [
+      "test:browser"
+    ]
   },
   "author": "Tonio Loewald",
   "license": "Apache-2.0",
@@ -52,8 +61,9 @@
   "devDependencies": {
     "bun-types": "^1.3.0",
     "chokidar": "^4.0.3",
-    "haltija": "1.12.9",
+    "haltija": "^1.13.0-beta.1",
     "happy-dom": "^20.14.0",
+    "playwright": "^1.63.0",
     "prettier": "^2",
     "tjs-lang": "^0.13.1",
     "tosijs": "^1.10.1",