@weasel-js/text-dom 1.9.4 → 1.10.1

package/README.md

@@ -5,7 +5,7 @@ writes styled runs.
 
 Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
 scene-graph canvas kit for React. See the
-[API reference](https://orochi235.github.io/weasel/api/).
+[API reference](https://orochi235.github.io/weasel/#pkg/text-dom).
 
 ```sh
 npm install @weasel-js/text-dom
@@ -22,6 +22,11 @@ While an edit is open the hook reports the selection's shared style
 (`MIXED` where the selected runs disagree) and applies a style or a flag such
 as bold to the selected range.
 
+A paste or a drop goes in as runs, never as the clipboard's markup: its blocks
+become lines, its table cells are set apart by tabs, and it keeps its bold,
+italic, underline, strikethrough, overline, and super- and subscript. Face,
+size, and color come from the text it lands in.
+
 `runsToDom` and `domToRuns` are the conversion between runs and the overlay's
 DOM, and `charOffsetToDomPosition` / `domPositionToCharOffset` map a character
 offset in the text to a DOM position and back.

package/dist/index.d.ts

@@ -1,15 +1,6 @@
 import { FlagKey, StyledRun, TextStyle, TextVerticalAlign, TextPaint, RangeStyle, RunStylePatch, ResolvedTextStyle } from '@weasel-js/text';
 
-/**
- * In-place text editing via a contenteditable overlay positioned over the
- * text node's screen-space pose. Enter / blur commit; Shift+Enter inserts a
- * newline; Escape cancels. The hook owns the DOM lifecycle of the overlay
- * element — caller just provides a container, the lookup hooks, and a
- * `setText` callback (which is responsible for op-batching/undo).
- *
- * The text layer should hide the node it's currently editing
- * (`isHidden: (n) => n.id === editingId`) so the overlay isn't drawn twice.
- */
+/** The option, return, and pose types of `useTextEdit`. */
 
 /**
  * A styling a shortcut or a control toggles. The additive booleans, plus the
@@ -56,18 +47,19 @@ interface TextEditScreenPose {
      * transform does the world→screen conversion.
      *
      * This is the only way run-level typography can be correct at a zoom other
-     * than 1. `runsToDom` emits run `fontSize` / `letterSpacing` in world units
-     * and `domToRuns` reads them straight back; threading a scale through the
-     * writer and its inverse through the reader would go lossy on fractional
-     * zooms. Scaling the whole overlay instead leaves that serializer pure and
-     * scales node-level and run-level values by the same factor for free.
-     *
-     * Omit it (the default, `1`) and the pose is plain screen pixels — the hook
-     * then infers the world→screen factor from `fontSize / style.fontSize` to
-     * scale node-level `letterSpacing`, and run-level overrides are left
-     * unscaled. Correct only at zoom 1.
+     * than 1. Omit it (the default, `1`) and the pose is plain screen pixels —
+     * the hook then infers the world→screen factor from
+     * `fontSize / style.fontSize` to scale node-level `letterSpacing`, and
+     * run-level overrides are left unscaled.
      */
     zoom?: number;
+    /**
+     * The frame the text is drawn in, when its box is turned or skewed: the
+     * linear part `[a, b, c, d]` (`x' = a·x + c·y`, `y' = b·x + d·y`) applied
+     * about the box's center. `x`, `y`, `width`, and `height` stay those of
+     * the box before it. Absent is the identity.
+     */
+    frame?: readonly [a: number, b: number, c: number, d: number];
 }
 /** A box in CSS pixels relative to `useTextEdit`'s `container`. */
 interface TextEditClipRect {
@@ -144,8 +136,7 @@ interface UseTextEditOptions {
      * commit calls both `setText` (with `runsToPlainText(runs)`) and
      * `setRuns(id, runs)` — but only when runs are actually in play: the node
      * already had some, or the edit produced styling. A plain-text edit of a
-     * plain-text node still calls `setText` alone, so a node that has never
-     * been styled doesn't grow a single-run `runs` array just for being edited.
+     * plain-text node still calls `setText` alone.
      */
     setRuns?: (id: string, runs: StyledRun[]) => void;
     /**
@@ -153,8 +144,7 @@ interface UseTextEditOptions {
      * color popover, anything whose whole purpose is to style the text being
      * edited? Focus moving into one does not end the edit.
      *
-     * Without this, the controls the feature exists for are exactly what
-     * destroys it: clicking a size field blurs the overlay, blur commits, and
+     * Without this, clicking a size field blurs the overlay, blur commits, and
      * the caret the control was about to act on is gone. Toggle buttons can
      * dodge it by `preventDefault()`-ing their own mousedown, but a field the
      * user has to type into cannot.
@@ -166,15 +156,21 @@ interface UseTextEditOptions {
     /** What Escape does to the edit: `'cancel'` (the default) drops it,
      *  `'commit'` keeps the text as Enter would. */
     escape?: 'cancel' | 'commit';
+    /** Called as an edit of `id` opens, from the call that opens it. */
+    onStart?: (id: string) => void;
+    /**
+     * Called as the edit of `id` closes, however it does: a commit, a cancel,
+     * a click away, or another edit opening over it. A commit has been written
+     * by then. Not called when the hook unmounts with an edit open.
+     */
+    onEnd?: (id: string) => void;
     /**
      * How long, in ms, an edit opening waits for the overlay's face before
      * showing the text in the fallback. Defaults to {@link TEXT_EDIT_FONT_HOLD}.
      *
      * The overlay stands in for canvas text the host has hidden, so the wait
      * shows nothing at all; past it, the fallback shows and reflows to the real
-     * face when that lands. A face already loaded — the usual case, since
-     * `@weasel-js/font` builds it as soon as its bytes arrive — shows at once.
-     * `0` never waits.
+     * face when that lands. A face already loaded shows at once. `0` never waits.
      */
     fontHold?: number;
 }
@@ -186,10 +182,8 @@ interface UseTextEditOptions {
 declare const TEXT_EDIT_FONT_HOLD = 100;
 /** Options for `useTextEdit().startEdit`. */
 interface StartEditOptions {
-    /**
-     * Where to place the caret on edit start. Number = caret offset (0..text.length);
-     * `'all'` selects the whole text (default — preserves the prior behavior).
-     */
+    /** Where to place the caret on edit start. Number = caret offset (0..text.length);
+     *  `'all'` selects the whole text (default). */
     caret?: number | 'all';
 }
 /** Return shape of `useTextEdit`. */
@@ -215,7 +209,7 @@ interface UseTextEditReturn {
     * n" stay distinguishable — a styling written at a collapsed caret arms
     * {@link UseTextEditReturn.pendingStyle} instead of restyling a range.
     *
-    * Follows the DOM selection, which browsers (and jsdom) report from a task
+    * Follows the DOM selection, which browsers report from a task
     * rather than synchronously; anything this hook writes itself updates it
     * synchronously. A DOM selection that leaves the overlay does **not** clear
     * it: that is what happens when the user clicks a styling control, and
@@ -240,10 +234,15 @@ interface UseTextEditReturn {
      * Styling armed at a collapsed caret, applied to the next character typed
      * and then dropped. `{}` when nothing is armed — which is always the case
      * while `selection` covers a real range, since a range is styled directly.
-     *
-     * Moving the caret abandons it, as in any other editor.
+     * Moving the caret abandons it.
      */
     pendingStyle: RunStylePatch;
+    /**
+     * What a styling control shows during an edit: the node's own style and
+     * paint, `rangeStyle` over it, and `pendingStyle` last — what the user
+     * will see themselves type. `null` when nothing is being edited.
+     */
+    effectiveStyle: RangeStyle | null;
     /**
      * Write `patch` over `selection`. A no-op with no active edit or an empty
      * patch. Over a real range this restyles the runs under it; at a collapsed
@@ -259,34 +258,20 @@ interface UseTextEditReturn {
      * re-selecting, and `rangeStyle` reflects the write before this returns.
      */
     applyStyleToSelection: (patch: RunStylePatch) => void;
-    /**
-     * Toggle one styling over `selection` — set it if the range doesn't
-     * uniformly carry it, clear it if it does. The shape a B / I / x² control
-     * or a keyboard shortcut wants, and what this hook's own shortcuts call.
-     */
+    /** Toggle one styling over `selection` — set it if the range doesn't
+     *  uniformly carry it, clear it if it does. */
     toggleStyle: (toggle: StyleToggle) => void;
 }
-/** In-place text editing via a contenteditable overlay positioned over the text node's screen-space pose. */
-declare function useTextEdit(opts: UseTextEditOptions): UseTextEditReturn;
-/**
- * The overlay's `top`, in container pixels, for content `contentHeight` tall
- * (pre-scale, like the rest of `pose`): the pose's top, shifted by the same
- * `verticalAlign` slack the canvas applies, plus `drop` — how far below the
- * CSS line's baseline the canvas puts its own, from {@link baselineDrop}.
- * @internal
- */
-declare function overlayTop(pose: TextEditScreenPose, contentHeight: number, drop?: number): number;
+
 /**
- * The canvas and CSS both hang a line's baseline half the leading plus one
- * ascent below the line top, from the same ascent rule, but each engine
- * rounds the font's metrics and that leading its own way, and a face that
- * states no ascent and descent hangs from its ascent alone. So the difference
- * is read from both sides rather than predicted: the canvas's from its own layout, the
- * overlay's from a zero-height inline box on a hidden line set exactly as the
- * overlay is. Pre-scale; `0` when either side has nothing to measure.
- * @internal
+ * In-place text editing via a contenteditable overlay positioned over the
+ * text node's screen-space pose. Enter / blur commit; Shift+Enter inserts a
+ * newline. The text layer should hide the node it's currently editing
+ * (`isHidden: (n) => n.id === editingId`) so the overlay isn't drawn twice.
  */
-declare function baselineDrop(el: HTMLElement, style: ResolvedTextStyle, pose: TextEditScreenPose, lineHeight: number): number;
+
+/** In-place text editing via a contenteditable overlay positioned over the text node's screen-space pose. */
+declare function useTextEdit(opts: UseTextEditOptions): UseTextEditReturn;
 
 /**
  * The DOM position of plain-text character position `offset`: a text node
@@ -313,20 +298,15 @@ declare function charOffsetToDomPosition(parent: HTMLElement, offset: number): {
 declare function domPositionToCharOffset(parent: HTMLElement, node: Node, offset: number): number;
 
 /**
- * Pure DOM ↔ `StyledRun[]` serializers for the contenteditable overlay
- * used by `useTextEdit`. The overlay's children are a flat sequence of
- * `<span data-run>` elements, each carrying one run's text and inline
- * styles. Newlines inside a run are literal `\n` characters; the overlay
- * has `white-space: pre-wrap` so they render as line breaks. The browser
- * breaks at no other UAX #14 hard break, so each of those is written as a
+ * DOM ↔ `StyledRun[]` serializers for the contenteditable overlay: a flat
+ * sequence of `<span data-run>` elements, one per run. The browser breaks at
+ * `\n` and at no other UAX #14 hard break, so each of those is written as a
  * `<span data-break>` holding a `\n` in its place — one character for one,
  * which keeps DOM offsets equal to source offsets.
  *
- * A small-caps run is the one exception to one text node per span: its
- * lowercase letters sit in `<span data-small-caps>` pieces, uppercased and
- * sized at the scale the canvas draws them with, since a browser's own
- * synthesis uses a fixed factor of its own. The pieces are presentation
- * only — `domToRuns` reads straight through them.
+ * A small-caps run's lowercase letters sit in `<span data-small-caps>` pieces,
+ * uppercased and sized at the scale the canvas draws them with, since a
+ * browser's own synthesis uses a fixed factor of its own.
  */
 
 /** Walk an overlay tree and emit a coalesced `StyledRun[]`. */
@@ -335,11 +315,9 @@ declare function domToRuns(parent: HTMLElement): StyledRun[];
  *  runs have it, and the face and transform that decide their pieces. */
 type OverlayRunBase = Pick<ResolvedTextStyle, 'fontFamily' | 'fontWeight' | 'fontStyle' | 'textTransform' | 'fontVariantCaps'>;
 /**
- * Build a flat sequence of `<span data-run>` children from `runs`, replacing
- * any existing children of `parent`. `base` is the node's style, which a run
- * inheriting small caps needs to be split by; without it the kit defaults
- * stand in.
+ * Replace `parent`'s children with one `<span data-run>` per run. `base` is
+ * the node's style, which a run inheriting small caps is split by.
  */
 declare function runsToDom(runs: readonly StyledRun[], parent: HTMLElement, base?: OverlayRunBase): void;
 
-export { type StartEditOptions, type StyleToggle, TEXT_EDIT_FONT_HOLD, type TextEditClipRect, type TextEditCommit, type TextEditScreenPose, type TextEditSelection, type UseTextEditOptions, type UseTextEditReturn, baselineDrop, charOffsetToDomPosition, domPositionToCharOffset, domToRuns, overlayTop, runsToDom, useTextEdit };
+export { type OverlayRunBase, type StartEditOptions, type StyleToggle, TEXT_EDIT_FONT_HOLD, type TextEditClipRect, type TextEditCommit, type TextEditScreenPose, type TextEditSelection, type UseTextEditOptions, type UseTextEditReturn, charOffsetToDomPosition, domPositionToCharOffset, domToRuns, runsToDom, useTextEdit };