@servicetitan/dte-pdf-editor 1.93.3 → 1.95.0

package/src/utils/field/__tests__/text-wrap.utils.test.ts

@@ -0,0 +1,181 @@
+import {
+    advanceWrap,
+    countWrappedLines,
+    INITIAL_WRAP_STATE,
+    type TextMeasurer,
+} from '../text-wrap.utils';
+
+/** Monospace: every code point is 10px wide, so a 100px box holds exactly 10 characters. */
+const monospace: TextMeasurer = text => Array.from(text).length * 10;
+
+describe('countWrappedLines', () => {
+    const subject = (text: string, maxWidth = 100, measure: TextMeasurer = monospace) => {
+        return countWrappedLines(text, maxWidth, measure);
+    };
+
+    describe('basic wrapping', () => {
+        test('an empty value still occupies one line', () => {
+            expect(subject('')).toBe(1);
+        });
+
+        test('text narrower than the box stays on one line', () => {
+            expect(subject('hello')).toBe(1);
+        });
+
+        test('text exactly as wide as the box does not wrap', () => {
+            expect(subject('aaaaaaaaaa')).toBe(1);
+        });
+
+        test('wraps at a word boundary instead of splitting the word', () => {
+            // "aaaa bbbb" is 9 chars and fits; " cccc" would end at 14 chars
+            expect(subject('aaaa bbbb cccc')).toBe(2);
+        });
+
+        test('wraps once per overflowing word', () => {
+            expect(subject('aaaaaaa bbbbbbb ccccccc ddddddd')).toBe(4);
+        });
+    });
+
+    describe('spaces', () => {
+        test('trailing spaces hang past the edge instead of creating a line', () => {
+            expect(subject('aaaaaaaaaa          ')).toBe(1);
+        });
+
+        test('spaces that hang push the next word onto the following line', () => {
+            expect(subject('aaaaaaaaaa      b')).toBe(2);
+        });
+
+        test('consecutive spaces are preserved and count towards the line width', () => {
+            expect(subject('a b', 50)).toBe(1);
+            expect(subject('a    b', 50)).toBe(2);
+        });
+
+        test('leading spaces count towards the first line', () => {
+            expect(subject('   aaaaaaaaaa')).toBe(2);
+        });
+    });
+
+    describe('explicit newlines', () => {
+        test('a newline forces a new line', () => {
+            expect(subject('a\nb')).toBe(2);
+        });
+
+        test('a trailing newline opens an empty line, as in a textarea', () => {
+            expect(subject('a\n')).toBe(2);
+        });
+
+        test('consecutive newlines each add a line', () => {
+            expect(subject('\n\n')).toBe(3);
+        });
+
+        test('treats CRLF and lone CR as a single line break', () => {
+            expect(subject('a\r\nb')).toBe(2);
+            expect(subject('a\rb')).toBe(2);
+        });
+
+        test('wraps each paragraph independently', () => {
+            expect(subject('aaaa bbbb cccc\ndd')).toBe(3);
+        });
+    });
+
+    describe('long unbroken words', () => {
+        test('breaks a word wider than the box between characters', () => {
+            // 25 chars at 10 per line: 10 + 10 + 5
+            expect(subject('a'.repeat(25))).toBe(3);
+        });
+
+        test('moves a long word to a fresh line before breaking it', () => {
+            // "ab " takes line 1, then the 25-char word fills 10 + 10 + 5
+            expect(subject(`ab ${'a'.repeat(25)}`)).toBe(4);
+        });
+
+        test('continues after a broken word on its last partial line', () => {
+            // the 25-char word leaves 50px free on its last line, enough for " bbbb"
+            expect(subject(`${'a'.repeat(25)} bbbb`)).toBe(3);
+        });
+
+        test('always places at least one character per line, even in a box narrower than a glyph', () => {
+            expect(subject('abc', 5)).toBe(3);
+        });
+    });
+
+    describe('proportional glyphs', () => {
+        const proportional: TextMeasurer = text => {
+            return Array.from(text).reduce((width, char) => {
+                if (char === 'i') {
+                    return width + 2;
+                }
+                if (char === 'W') {
+                    return width + 14;
+                }
+                return width + 8;
+            }, 0);
+        };
+
+        test('narrow glyphs pack far more characters per line than wide ones', () => {
+            expect(subject('i'.repeat(20), 100, proportional)).toBe(1);
+            expect(subject('W'.repeat(20), 100, proportional)).toBe(3);
+        });
+
+        test('line count depends on rendered width, not character count', () => {
+            const narrow = `${'i'.repeat(20)} ${'i'.repeat(20)} ${'i'.repeat(20)}`;
+            const wide = `${'W'.repeat(6)} ${'W'.repeat(6)} ${'W'.repeat(6)}`;
+            expect(narrow.length).toBeGreaterThan(wide.length);
+            expect(subject(narrow, 100, proportional)).toBeLessThan(
+                subject(wide, 100, proportional),
+            );
+        });
+    });
+
+    describe('unicode', () => {
+        test('never splits a surrogate pair when breaking a long word', () => {
+            // 25 code points (50 UTF-16 units): 10 + 10 + 5. Splitting units would give 5 lines.
+            expect(subject('😀'.repeat(25))).toBe(3);
+        });
+
+        test('breaks unspaced non-Latin text between characters', () => {
+            const cjk: TextMeasurer = text => Array.from(text).length * 20;
+            const text = '日本語のテキストです。あ';
+            // 12 full-width characters, 5 per 100px line: 5 + 5 + 2
+            expect(Array.from(text)).toHaveLength(12);
+            expect(subject(text, 100, cjk)).toBe(3);
+        });
+    });
+});
+
+describe('advanceWrap', () => {
+    const subject = (state: typeof INITIAL_WRAP_STATE, text: string, maxWidth = 100) => {
+        return advanceWrap(state, text, maxWidth, monospace);
+    };
+
+    test('starts from an empty box that already occupies one line', () => {
+        expect(INITIAL_WRAP_STATE).toEqual({ lines: 1, lineWidth: 0 });
+        expect(subject(INITIAL_WRAP_STATE, '')).toEqual({ lines: 1, lineWidth: 0 });
+    });
+
+    test('reports the lines used and how full the last one is', () => {
+        expect(subject(INITIAL_WRAP_STATE, 'aaaa bbbb cccc')).toEqual({ lines: 2, lineWidth: 40 });
+    });
+
+    test('resuming from a state gives the same result as laying everything out at once', () => {
+        const first = 'aaaa bbbb ';
+        const second = 'cccc dddd eeee ffffffffff gggg\nhh ';
+
+        const resumed = subject(subject(INITIAL_WRAP_STATE, first), second);
+
+        expect(resumed).toEqual(subject(INITIAL_WRAP_STATE, first + second));
+        expect(resumed.lines).toBe(countWrappedLines(first + second, 100, monospace));
+    });
+
+    test('a newline resets the line, whatever came before', () => {
+        expect(subject({ lines: 2, lineWidth: 80 }, '\nab')).toEqual({ lines: 3, lineWidth: 20 });
+    });
+
+    test('does not change the state it is given', () => {
+        const state = { lines: 1, lineWidth: 30 };
+
+        subject(state, 'aaaa bbbb cccc dddd');
+
+        expect(state).toEqual({ lines: 1, lineWidth: 30 });
+    });
+});

package/src/utils/field/field-text-box.utils.ts

@@ -0,0 +1,143 @@
+import { type CSSProperties } from 'react';
+import { FieldTypeEnum, type PdfField } from '../../interface/types';
+import { getFieldFontSizeInPixels } from './get-field-font-size.utils';
+import { getFieldTypographyStyle } from './get-field-typography.utils';
+import { advanceWrap, INITIAL_WRAP_STATE, type TextMeasurer } from './text-wrap.utils';
+
+export type FieldTextLayout = 'single-line' | 'multiline' | 'number';
+
+/** Tolerance for float noise, so an exact fit (e.g. 28 x 7.1px in 198.8px) isn't rejected. */
+export const EPSILON = 1e-6;
+
+/**
+ * `.dte-pdf-field-fillable` box model (pdf-field-overlay.css): no padding or border, and
+ * `line-height: 1`. Update together with the CSS if either changes.
+ */
+const FILLABLE_TEXT_INSET_PX = { horizontal: 0, vertical: 0 };
+const FILLABLE_LINE_HEIGHT_RATIO = 1;
+
+/**
+ * Chrome keeps the inner spin button's 15px gutter free of text in `<input type="number">` even
+ * while the button is hidden, so a long value is clipped by this much. Applied in every browser,
+ * so one that doesn't reserve it is at worst slightly conservative.
+ */
+const NUMBER_INPUT_SPIN_BUTTON_PX = 15;
+
+/** Per-glyph width (em) used when canvas measurement isn't available (SSR, jsdom). */
+const FALLBACK_TEXT_WIDTH_EM = 0.46;
+const FALLBACK_DIGIT_WIDTH_EM = 0.556;
+const FALLBACK_BOLD_WIDTH_FACTOR = 1.06;
+
+/** What a text-entry field offers to lay text out in, with a way to measure that text. */
+export interface FieldTextBox {
+    layout: FieldTextLayout;
+    /** Content-box width in px (field width minus horizontal padding and borders). */
+    width: number;
+    /** Content-box height in px. */
+    height: number;
+    /** Height of one line box in px. */
+    lineHeight: number;
+    measure: TextMeasurer;
+    /** Same key, same geometry and font: results for it can be shared. */
+    key: string;
+}
+
+let measureContext: CanvasRenderingContext2D | null | undefined;
+
+const getMeasureContext = (): CanvasRenderingContext2D | null => {
+    if (measureContext === undefined) {
+        measureContext =
+            typeof document === 'undefined'
+                ? null
+                : (document.createElement('canvas').getContext('2d') ?? null);
+    }
+    return measureContext;
+};
+
+interface FieldTypography extends Pick<CSSProperties, 'fontFamily' | 'fontWeight'> {
+    fontSizePx: number;
+}
+
+const createTextMeasurer = (
+    { fontFamily, fontSizePx, fontWeight }: FieldTypography,
+    layout: FieldTextLayout,
+): TextMeasurer => {
+    const ctx = getMeasureContext();
+
+    if (!ctx) {
+        const isBold = fontWeight === 'bold';
+        const widthEm =
+            layout === 'number'
+                ? FALLBACK_DIGIT_WIDTH_EM
+                : FALLBACK_TEXT_WIDTH_EM * (isBold ? FALLBACK_BOLD_WIDTH_FACTOR : 1);
+        return text => text.length * fontSizePx * widthEm;
+    }
+
+    const font = `${fontWeight} ${fontSizePx}px ${fontFamily}`;
+    return text => {
+        ctx.font = font;
+        return ctx.measureText(text).width;
+    };
+};
+
+const getFieldTextLayout = (field: PdfField): FieldTextLayout | undefined => {
+    if (field.type !== FieldTypeEnum.fillable) {
+        return undefined;
+    }
+    if (field.subType === 'number') {
+        return 'number';
+    }
+    if (field.subType === 'text') {
+        return field.multiline ? 'multiline' : 'single-line';
+    }
+    return undefined;
+};
+
+/**
+ * The measurable text box of a fillable `text`/`number` field, measured with canvas at the
+ * field's own font family, weight and size. `undefined` for every other kind of field.
+ */
+export const getFieldTextBox = (field: PdfField): FieldTextBox | undefined => {
+    const layout = getFieldTextLayout(field);
+    if (!layout) {
+        return undefined;
+    }
+
+    const { fontFamily, fontWeight } = getFieldTypographyStyle(field);
+    const fontSizePx = getFieldFontSizeInPixels(field);
+    const spinButtonWidth = layout === 'number' ? NUMBER_INPUT_SPIN_BUTTON_PX : 0;
+    const width = field.width - 2 * FILLABLE_TEXT_INSET_PX.horizontal - spinButtonWidth;
+    const height = field.height - 2 * FILLABLE_TEXT_INSET_PX.vertical;
+
+    return {
+        layout,
+        width,
+        height,
+        lineHeight: fontSizePx * FILLABLE_LINE_HEIGHT_RATIO,
+        measure: createTextMeasurer({ fontFamily, fontSizePx, fontWeight }, layout),
+        key: [layout, width, height, fontSizePx, fontWeight, fontFamily].join('|'),
+    };
+};
+
+/** Whole lines of text that fit the box height; always at least one. */
+export const getMaxLines = ({
+    height,
+    lineHeight,
+}: Pick<FieldTextBox, 'height' | 'lineHeight'>) => {
+    return Math.max(1, Math.floor(height / lineHeight + EPSILON));
+};
+
+/**
+ * Whether `text` fits the box without overflowing: its width on one line, or its wrapped lines.
+ * A single character always counts as fitting, so no field is ever left impossible to type in.
+ */
+export const doesTextFitBox = (box: FieldTextBox, text: string): boolean => {
+    if (Array.from(text).length <= 1) {
+        return true;
+    }
+    if (box.layout === 'multiline') {
+        const { lines } = advanceWrap(INITIAL_WRAP_STATE, text, box.width, box.measure);
+        return lines <= getMaxLines(box);
+    }
+    return box.measure(text) <= box.width + EPSILON;
+};

package/src/utils/field/fit-field-text.utils.ts

@@ -0,0 +1,61 @@
+import { type PdfField } from '../../interface/types';
+import { doesTextFitBox, getFieldTextBox } from './field-text-box.utils';
+import { findLargestFit } from './get-field-max-length.utils';
+
+/** Splits `next` into what `previous` and `next` share at both ends, and what sits between. */
+const getInsertion = (previous: string, next: string) => {
+    const shorter = Math.min(previous.length, next.length);
+
+    let headLength = 0;
+    while (headLength < shorter && previous[headLength] === next[headLength]) {
+        headLength += 1;
+    }
+
+    let tailLength = 0;
+    while (
+        tailLength < shorter - headLength &&
+        previous[previous.length - 1 - tailLength] === next[next.length - 1 - tailLength]
+    ) {
+        tailLength += 1;
+    }
+
+    return {
+        head: next.slice(0, headLength),
+        inserted: next.slice(headLength, next.length - tailLength),
+        tail: next.slice(next.length - tailLength),
+    };
+};
+
+/**
+ * The value a fillable `text`/`number` field should take when its text goes from `previousValue`
+ * to `nextValue`: `nextValue` when the text fits the field, otherwise as much of it as fits.
+ *
+ * Fit is measured from the rendered text (width on one line, wrapped lines in a multiline
+ * field), so narrow text keeps filling the field after wide text has stopped. Like the native
+ * `maxLength`, it is the text just inserted or pasted that is cut back, never what was already
+ * there, and an edit that would only add overflow is refused outright. Deleting is always allowed,
+ * even from a value that already overflows.
+ */
+export const fitFieldTextChange = (
+    field: PdfField,
+    previousValue: string,
+    nextValue: string,
+): string => {
+    const box = getFieldTextBox(field);
+    if (!box || doesTextFitBox(box, nextValue)) {
+        return nextValue;
+    }
+
+    const { head, inserted, tail } = getInsertion(previousValue, nextValue);
+    const insertedChars = Array.from(inserted);
+    const withInserted = (count: number) => {
+        return head + insertedChars.slice(0, count).join('') + tail;
+    };
+
+    const keep = findLargestFit(
+        count => doesTextFitBox(box, withInserted(count)),
+        insertedChars.length,
+    );
+
+    return keep === 0 && insertedChars.length > 0 ? previousValue : withInserted(keep);
+};

package/src/utils/field/get-field-max-length.utils.ts

@@ -0,0 +1,211 @@
+import { type PdfField } from '../../interface/types';
+import { EPSILON, getFieldTextBox, getMaxLines, type FieldTextBox } from './field-text-box.utils';
+import {
+    advanceWrap,
+    INITIAL_WRAP_STATE,
+    type TextMeasurer,
+    type WrapState,
+} from './text-wrap.utils';
+
+/**
+ * Typical free-text form entries (names, addresses, emails, short notes) in mixed case.
+ *
+ * Capacity is estimated for this text rather than for a uniform `A-Za-z0-9` alphabet: that one
+ * averages ~0.58em per glyph against ~0.46em here (and ~0.47em for real entries), which is why
+ * the previous estimate under-reported capacity by ~20%. Contains no hyphens or newlines, so
+ * the wrap simulation in `text-wrap.utils` stays exact for it.
+ */
+const TEXT_SAMPLE =
+    'Jonathan Alexander Smith 1234 Elm Street, Apartment 5B Springfield, IL 62704 ' +
+    'jonathan.smith@example.com Maria Garcia Lopez Estimate #48213 for $1,250.00 ' +
+    'Replace the capacitor and clean the coils. Call before arriving, gate code 4471. ' +
+    'Dana Whitfield, Park Avenue Plumbing ';
+
+/** Glyphs a user can type into a number field; the capacity is bounded by the widest of them. */
+const NUMBER_GLYPHS = '0123456789.-';
+
+/** Evenly spaced word-start offsets into the sample that multiline wrapping is averaged over. */
+const MULTILINE_SAMPLE_PHASES = 8;
+
+/** Hard stop for the search, so a degenerate measurer (zero-width glyphs) can't loop forever. */
+const MAX_CAPACITY = 10_000;
+
+/**
+ * Largest `length` in `[0, max]` for which `fits(length)` holds; `fits` must be monotone
+ * (once a length stops fitting, longer ones don't either) and `fits(0)` is taken as true.
+ */
+export const findLargestFit = (fits: (length: number) => boolean, max = MAX_CAPACITY): number => {
+    let low = 0;
+    let high = max + 1;
+
+    for (let probe = 1; probe < high; probe *= 2) {
+        if (!fits(probe)) {
+            high = probe;
+            break;
+        }
+        low = probe;
+    }
+
+    while (high - low > 1) {
+        const mid = Math.floor((low + high) / 2);
+        if (fits(mid)) {
+            low = mid;
+        } else {
+            high = mid;
+        }
+    }
+
+    return low;
+};
+
+/** The sample starting at `start` and wrapping around, repeated to `length` characters. */
+const getSampleText = (start: number, length: number) => {
+    const rotated = TEXT_SAMPLE.slice(start) + TEXT_SAMPLE.slice(0, start);
+    return rotated.repeat(Math.ceil(length / rotated.length)).slice(0, length);
+};
+
+const SAMPLE_WORD_STARTS = Array.from(TEXT_SAMPLE, (char, index) => index).filter(index => {
+    return TEXT_SAMPLE[index] !== ' ' && (index === 0 || TEXT_SAMPLE[index - 1] === ' ');
+});
+
+const SAMPLE_PHASES = Array.from({ length: MULTILINE_SAMPLE_PHASES }, (_, index) => {
+    return SAMPLE_WORD_STARTS[
+        Math.floor((index * SAMPLE_WORD_STARTS.length) / MULTILINE_SAMPLE_PHASES)
+    ];
+});
+
+type TextBoxGeometry = Omit<FieldTextBox, 'key'>;
+
+const getRemainingWidth = ({ measure, width }: TextBoxGeometry, value: string) => {
+    return Math.max(0, width - measure(value));
+};
+
+/**
+ * Number inputs only ever hold digits, `.` and `-`, so every value of N characters is at most
+ * N widest-glyphs wide: the room left is a guaranteed fit, not an average.
+ */
+const estimateNumberRoom = (box: TextBoxGeometry, value: string) => {
+    const widestGlyph = Math.max(...Array.from(NUMBER_GLYPHS, glyph => box.measure(glyph)));
+    return Math.floor(getRemainingWidth(box, value) / widestGlyph + EPSILON);
+};
+
+/** Characters of typical text that fit in the width left: it over the sample's mean glyph. */
+const estimateSingleLineRoom = (box: TextBoxGeometry, value: string) => {
+    const meanGlyphWidth = box.measure(TEXT_SAMPLE) / TEXT_SAMPLE.length;
+    return Math.floor(getRemainingWidth(box, value) / meanGlyphWidth + EPSILON);
+};
+
+/**
+ * Characters of typical text that fit in the lines left after `value`. Real wrapping is
+ * simulated, so the unused space at the end of each line is accounted for; the result is
+ * averaged over several starting points in the sample because it shifts by a few characters
+ * with where the text begins.
+ */
+const estimateMultilineRoom = (box: TextBoxGeometry, value: string) => {
+    const maxLines = getMaxLines(box);
+    const measureCache = new Map<string, number>();
+    const measure: TextMeasurer = text => {
+        let measured = measureCache.get(text);
+        if (measured === undefined) {
+            measured = box.measure(text);
+            measureCache.set(text, measured);
+        }
+        return measured;
+    };
+
+    const valueState = advanceWrap(INITIAL_WRAP_STATE, value, box.width, measure);
+    if (valueState.lines > maxLines) {
+        return 0;
+    }
+
+    // typed text goes on after a word, so continue it with a space unless it already ends in one
+    const separator = /(^|[ \n])$/.test(value) ? '' : ' ';
+    const fitsAfterValue = (state: WrapState, text: string) => {
+        return advanceWrap(state, text, box.width, measure).lines <= maxLines;
+    };
+
+    const capacities = SAMPLE_PHASES.map(start => {
+        return findLargestFit(length => {
+            return fitsAfterValue(valueState, separator + getSampleText(start, length));
+        });
+    });
+
+    return Math.floor(capacities.reduce((sum, value) => sum + value, 0) / capacities.length);
+};
+
+export type TextCapacityParams = TextBoxGeometry & {
+    /** What is already typed; it counts towards the capacity and uses up some of the room. */
+    value?: string;
+};
+
+/**
+ * Highest character count a text box can hold, from rendered text widths: the characters
+ * already in `value` plus how many more fit after it.
+ *
+ * - `number`: guaranteed fit, bounded by the widest of the digits, `.` and `-`
+ * - `single-line`: expected fit for typical text, from the mean glyph width of a sample
+ * - `multiline`: expected fit for typical text, from simulated word wrapping into the
+ *   `floor(height / lineHeight)` lines available
+ *
+ * Narrow text leaves more room than wide text, so the answer moves with what is typed. A
+ * value that already overflows has no room left: the capacity is just its own length.
+ * At least 1; `undefined` when `measure` yields no usable text width, since there is then
+ * no basis for a limit.
+ */
+export const estimateTextCapacity = ({
+    value = '',
+    ...box
+}: TextCapacityParams): number | undefined => {
+    const sampleWidth = box.measure(TEXT_SAMPLE);
+    if (!Number.isFinite(sampleWidth) || sampleWidth <= 0) {
+        return undefined;
+    }
+
+    let room: number;
+    switch (box.layout) {
+        case 'number':
+            room = estimateNumberRoom(box, value);
+            break;
+        case 'multiline':
+            room = estimateMultilineRoom(box, value);
+            break;
+        default:
+            room = estimateSingleLineRoom(box, value);
+    }
+
+    return Number.isNaN(room)
+        ? undefined
+        : Math.max(1, value.length + Math.min(MAX_CAPACITY, room));
+};
+
+const MAX_LENGTH_CACHE_SIZE = 500;
+const maxLengthCache = new Map<string, number | undefined>();
+
+/**
+ * Max character count a fillable `text`/`number` field can hold given what is typed in it, so
+ * the counter can say how much room is left. With no `value` it is the field's capacity when
+ * empty. Input is limited by what actually fits, see `fitFieldTextChange`, not by this count.
+ *
+ * See {@link estimateTextCapacity} for how each field kind is measured. Text is measured
+ * with canvas at the field's own font, so it follows family, weight and size.
+ */
+export const getFieldMaxLength = (field: PdfField, value = ''): number | undefined => {
+    const box = getFieldTextBox(field);
+    if (!box) {
+        return undefined;
+    }
+
+    const cacheKey = `${box.key}|${value}`;
+    if (maxLengthCache.has(cacheKey)) {
+        return maxLengthCache.get(cacheKey);
+    }
+
+    const maxLength = estimateTextCapacity({ ...box, value });
+
+    if (maxLengthCache.size >= MAX_LENGTH_CACHE_SIZE) {
+        maxLengthCache.clear();
+    }
+    maxLengthCache.set(cacheKey, maxLength);
+
+    return maxLength;
+};

package/src/utils/field/index.ts

@@ -5,8 +5,10 @@ export * from './field-drag.utils';
 export * from './field-placeholder-text.utils';
 export * from './field-reading-order.utils';
 export * from './field-resize.utils';
+export * from './fit-field-text.utils';
 export * from './get-field-bounds-style.utils';
 export * from './get-field-font-size.utils';
+export * from './get-field-max-length.utils';
 export * from './get-field-text-clip.utils';
 export * from './get-field-type-option.utils';
 export * from './get-field-typography.utils';

package/src/utils/field/text-wrap.utils.ts

@@ -0,0 +1,78 @@
+/** Returns the rendered width of `text` in pixels for one fixed font. */
+export type TextMeasurer = (text: string) => number;
+
+/** Where text wrapping has got to: the line being filled, and how wide it is so far. */
+export interface WrapState {
+    lines: number;
+    lineWidth: number;
+}
+
+/** An empty box still occupies one line. */
+export const INITIAL_WRAP_STATE: WrapState = { lines: 1, lineWidth: 0 };
+
+/**
+ * Continues laying out `text` after `state` in a box `maxWidth` wide, simulating browser layout
+ * for `white-space: pre-wrap; overflow-wrap: break-word` (the multiline fillable textarea):
+ *
+ * - `\n` forces a line break; a trailing `\n` still opens a line, as in a textarea
+ * - words wrap at spaces; runs of spaces are preserved and hang past the edge instead of wrapping
+ * - a word wider than a whole line is broken between characters (code points)
+ *
+ * `text` must start at a word boundary of the text already laid out, i.e. not continue a word.
+ *
+ * Not modelled: break opportunities after hyphens and other punctuation, which only ever let
+ * browsers pack lines more tightly, so the line count is never optimistic.
+ */
+export const advanceWrap = (
+    state: WrapState,
+    text: string,
+    maxWidth: number,
+    measure: TextMeasurer,
+): WrapState => {
+    let { lineWidth, lines } = state;
+
+    for (const token of text.replace(/\r\n?/g, '\n').match(/\n| +|[^ \n]+/g) ?? []) {
+        if (token === '\n') {
+            lines += 1;
+            lineWidth = 0;
+            continue;
+        }
+
+        const tokenWidth = measure(token);
+
+        if (token[0] === ' ' || lineWidth + tokenWidth <= maxWidth) {
+            lineWidth += tokenWidth;
+            continue;
+        }
+
+        if (lineWidth > 0) {
+            lines += 1;
+            lineWidth = 0;
+        }
+
+        if (tokenWidth <= maxWidth) {
+            lineWidth = tokenWidth;
+            continue;
+        }
+
+        for (const char of token) {
+            const charWidth = measure(char);
+            if (lineWidth > 0 && lineWidth + charWidth > maxWidth) {
+                lines += 1;
+                lineWidth = 0;
+            }
+            lineWidth += charWidth;
+        }
+    }
+
+    return { lines, lineWidth };
+};
+
+/** Counts the lines `text` occupies in a box `maxWidth` wide; see {@link advanceWrap}. */
+export const countWrappedLines = (
+    text: string,
+    maxWidth: number,
+    measure: TextMeasurer,
+): number => {
+    return advanceWrap(INITIAL_WRAP_STATE, text, maxWidth, measure).lines;
+};