@weasel-js/text-dom 0.0.0-stage → 1.9.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @weasel-js/text-dom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+In-place text editing over a canvas: a `contenteditable` overlay that reads and
+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/).
+
+```sh
+npm install @weasel-js/text-dom
+```
+
+`useTextEdit` mounts an editable element over a box on screen, set in the same
+face, size, and alignment the canvas draws the text in, and hands back the
+edited text as `StyledRun`s from `@weasel-js/text` when the edit commits. It
+takes a screen pose and a `TextStyle`; it does not know about a scene graph or
+a renderer. `useSceneTextEdit` in `@weasel-js/core` is this hook wired to a
+scene node.
+
+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.
+
+`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

@@ -0,0 +1,345 @@
+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.
+ */
+
+/**
+ * A styling a shortcut or a control toggles. The additive booleans, plus the
+ * two `script` values — which are exclusive rather than additive, so they
+ * toggle against one enum rather than each owning a boolean.
+ */
+type StyleToggle = FlagKey | 'super' | 'sub';
+/**
+ * The caret's character range within the text being edited. Half-open
+ * `[start, end)` over the concatenated run text, normalized so `start <= end`
+ * regardless of which way the user dragged. `start === end` is a collapsed
+ * caret — a real position, not the absence of one, which is why the hook
+ * reports `null` rather than a zero-width range when there is no caret.
+ */
+interface TextEditSelection {
+    start: number;
+    end: number;
+}
+/** Screen-space pose passed to `useTextEdit` so the overlay can be placed and sized in CSS pixels. */
+interface TextEditScreenPose {
+    /** Top-left in CSS pixels relative to `container`. Always screen pixels,
+     *  including when `zoom` is set — the scale is anchored at this point, not
+     *  translated by it. */
+    x: number;
+    y: number;
+    /** Pre-scale — CSS pixels, or world units when `zoom` is set. */
+    width: number;
+    height: number;
+    /** Pre-scale font size: `style.fontSize * zoom` when `zoom` is omitted, the
+     *  world-unit `style.fontSize` when it is set. */
+    fontSize: number;
+    /** Effective on-screen line height multiplier (defaults to style.lineHeight). */
+    lineHeight?: number;
+    /**
+     * Where the text sits within `height`, as the canvas places it. `'center'`
+     * and `'bottom'` size the overlay to its own content and offset it by the
+     * slack, re-measured as typing changes the line count. Default `'top'`.
+     */
+    verticalAlign?: TextVerticalAlign;
+    /**
+     * CSS scale applied to the overlay (`transform: scale(zoom)`, anchored at
+     * its top-left). Every other size on this pose, and every typographic
+     * metric the hook writes, is then **pre-scale** — pass world units and the
+     * 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.
+     */
+    zoom?: number;
+}
+/** A box in CSS pixels relative to `useTextEdit`'s `container`. */
+interface TextEditClipRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** What one edit session changed, as `UseTextEditOptions.commit` receives it. */
+interface TextEditCommit {
+    text: string;
+    runs?: StyledRun[];
+    style?: TextStyle;
+}
+/** Options for `useTextEdit`. */
+interface UseTextEditOptions {
+    /** Element the overlay is appended to. Must be `position: relative`/absolute. */
+    container: HTMLElement | null;
+    /** Read the current text for `id`. */
+    getText: (id: string) => string;
+    /** Read style for `id` (used for font setup on the overlay). */
+    getStyle: (id: string) => TextStyle | undefined;
+    /**
+     * Read the node's paint for `id` — its `data.fill` / `data.stroke`. The
+     * overlay paints its text and caret from the fill, so omitting this
+     * renders every node's editor in the default black however the node
+     * itself is painted.
+     */
+    getPaint?: (id: string) => TextPaint | undefined;
+    /**
+     * Write style back for `id`. Optional; needed only to turn a flag **off**
+     * inside a node whose own `TextStyle` sets it. Run flags are additive, so
+     * that edit is expressed by lowering the node flag and raising it on the
+     * runs outside the selection — which needs somewhere to put the new node
+     * style. Without this or `commit`, such a toggle is declined and nothing
+     * changes. See `flagRange` in `@weasel-js/text`.
+     *
+     * Called when the edit commits, never during it: the session holds the
+     * rewritten style until then (see `UseTextEditReturn.nodeStyle`), so a
+     * canceled edit writes nothing.
+     */
+    setStyle?: (id: string, style: TextStyle) => void;
+    /** Read screen-space pose for `id`. Called per frame while editing. */
+    getScreenPose: (id: string) => TextEditScreenPose | null;
+    /**
+     * The box, in CSS pixels relative to `container`, the overlay is visible
+     * within — where the canvas clips the glyphs the overlay stands in for.
+     * Re-read every frame. Omit it, or return `null`, to clip nothing.
+     *
+     * The clip cannot scroll, so a caret moving past its edge leaves the page
+     * where it is; a scrollable container would drag the canvas after the caret.
+     */
+    getClipRect?: () => TextEditClipRect | null;
+    /** Commit text. Caller wraps in op/undo. Required unless `commit` is given. */
+    setText?: (id: string, text: string) => void;
+    /**
+     * Take the whole edit in one call, so the caller can make it one write and
+     * one undo step. When given, it replaces `setText`, `setRuns`, and
+     * `setStyle`, none of which is called. `runs` is present when runs are in
+     * play (see `setRuns`), `style` when the edit rewrote the node's own style
+     * (see `setStyle`).
+     */
+    commit?: (id: string, edit: TextEditCommit) => void;
+    /**
+     * Optional: read the current rich-text runs for `id`. When provided AND
+     * returns a non-empty array, the overlay renders the runs as styled
+     * `<span data-run>` elements; otherwise the overlay is seeded with plain
+     * text via `getText`.
+     */
+    getRuns?: (id: string) => readonly StyledRun[] | undefined;
+    /**
+     * Optional: commit rich-text runs back to the node. When omitted, only
+     * `setText` is called with the plain-text form on commit. When provided,
+     * 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.
+     */
+    setRuns?: (id: string, runs: StyledRun[]) => void;
+    /**
+     * Is `el` part of the editor's own chrome — a character-options bar, a
+     * 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
+     * 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.
+     *
+     * Chrome focus does not disturb the reported `selection` either — see
+     * `UseTextEditReturn.selection`.
+     */
+    isEditorChrome?: (el: Element) => boolean;
+    /** What Escape does to the edit: `'cancel'` (the default) drops it,
+     *  `'commit'` keeps the text as Enter would. */
+    escape?: 'cancel' | 'commit';
+    /**
+     * 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.
+     */
+    fontHold?: number;
+}
+/**
+ * The default {@link UseTextEditOptions.fontHold}: at 100ms a blank edit
+ * still reads as an instant response, and it is the block period CSS gives
+ * `font-display: fallback` for the same trade.
+ */
+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).
+     */
+    caret?: number | 'all';
+}
+/** Return shape of `useTextEdit`. */
+interface UseTextEditReturn {
+    editingId: string | null;
+    startEdit: (id: string, opts?: StartEditOptions) => void;
+    cancelEdit: () => void;
+    /** End the edit and write it. An edit that leaves the text, the runs, and
+     *  the node's style as it found them writes nothing. */
+    commit: () => void;
+    isEditing: (id: string) => boolean;
+    /**
+     * The node-wide style this edit has rewritten and not yet written back, or
+     * `null` when it has rewritten none (the node's own style stands) or
+     * nothing is being edited. Lowering a flag the node sets rewrites it; the
+     * write waits for the commit. A control showing the node's style during an
+     * edit reads this first.
+     */
+    nodeStyle: TextStyle | null;
+    /**
+    * The caret's character range, or `null` when nothing is being edited. A
+    * collapsed caret reports `{ start: n, end: n }`, so `null` and "caret at
+    * 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
+    * 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
+    * reporting `null` there would read as "collapsed caret" and send the
+    * control's patch to the node instead of to the range. It is cleared on
+    * `startEdit` and when the edit ends.
+    */
+    selection: TextEditSelection | null;
+    /**
+     * The styling shared by every run in `selection` — a concrete value where
+     * the range agrees, `MIXED` where it doesn't. `null` exactly when
+     * `selection` is `null`. A collapsed caret reports the styling *at* the
+     * caret (the run to its left, or the run to its right at offset 0), which
+     * is what the next typed character inherits.
+     *
+     * This does not include {@link UseTextEditReturn.pendingStyle}. A control
+     * showing what the next character will look like wants both, merged in
+     * that order; one showing what is already written wants only this.
+     */
+    rangeStyle: RangeStyle | null;
+    /**
+     * 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.
+     */
+    pendingStyle: RunStylePatch;
+    /**
+     * 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
+     * caret it merges into `pendingStyle` instead, so the styling lands on
+     * what gets typed next rather than on text the user didn't select.
+     *
+     * Lowering a flag the *node* sets is neither of those — a run cannot say
+     * "not italic" — so it rewrites instead: the node flag is cleared and raised
+     * on every run outside the range. Bold is spared that: a run's own
+     * `fontWeight` can say "regular", so it is written over the range.
+     *
+     * The caret survives, so a second style can be applied without
+     * 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.
+     */
+    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
+ */
+declare function baselineDrop(el: HTMLElement, style: ResolvedTextStyle, pose: TextEditScreenPose, lineHeight: number): number;
+
+/**
+ * The DOM position of plain-text character position `offset`: a text node
+ * and an offset into it wherever one holds the position, otherwise an element
+ * and a child index (just past a `<br>` that ends the text). Offsets beyond
+ * the text clamp to its end. Returns `{ node: parent, offset: 0 }` for an
+ * overlay with no text.
+ */
+declare function charOffsetToDomPosition(parent: HTMLElement, offset: number): {
+    node: Node;
+    offset: number;
+} | null;
+/**
+ * Inverse of `charOffsetToDomPosition`: the characters that precede the DOM
+ * position `(node, offset)`.
+ *
+ * When `node` is an element the DOM offset indexes *child nodes*, not
+ * characters — `(overlay, 0)` is the start of the text and `(overlay,
+ * childNodes.length)` its end. That shape is not exotic: `Range.
+ * selectNodeContents`, which `useTextEdit` uses for its select-all caret,
+ * produces exactly it. So an element position is resolved by counting the
+ * pieces that end at or before the boundary point.
+ */
+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
+ * `<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.
+ */
+
+/** Walk an overlay tree and emit a coalesced `StyledRun[]`. */
+declare function domToRuns(parent: HTMLElement): StyledRun[];
+/** What a run inherits from its node, for the overlay's small caps: which
+ *  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.
+ */
+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 };