A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file ui-text-overflow.test.ts — what Clip and Ellipsis promise.
*
* Two of these decide whether a reader can tell "this line was long" from "there
* is more below": the mark goes on the last kept line whenever lines were
* dropped, and a box too short for one line still shows one.
*/
import { describe, it, expect } from 'vitest';
import {
GlyphAtlas, type GlyphRasterizer, type AtlasPageStore, type RasterGlyph,
} from '../src/ui/text/glyph-atlas';
import { layoutText, measureWidth, shrinkFontSize } from '../src/ui/text/layout';
import { drawTextWith } from '../src/ui/text/text-renderer';
import { TextOverflow } from '../src/ui/core/text';
function makeAtlas(): GlyphAtlas {
const rasterizer: GlyphRasterizer = {
renderSize: 48,
spread: 6,
rasterize: (cp: number): RasterGlyph => {
// A real font does not advance an ellipsis like a letter, and a fake
// that does makes the two modes indistinguishable by width — which is
// the only thing a layout hands back.
if (cp === 32) return { pixels: new Uint8Array(0), width: 0, height: 0, advance: 6, bearingX: 0, bearingY: 0 };
const advance = cp === 0x2026 ? 18 : 11;
return { pixels: new Uint8Array(10 * 12 * 4), width: 10, height: 12, advance, bearingX: 1, bearingY: 10 };
},
};
let next = 1;
const store: AtlasPageStore = { createPage: () => next++, uploadSubRegion: () => {} };
return new GlyphAtlas(rasterizer, store, { pageSize: 256, padding: 1 });
}
// scale 0.5 at this size: every letter advances 5.5px, a space 3px.
const F = 24;
const LINE = F * 1.2;
const atlas = makeAtlas();
const width = (s: string) => measureWidth(s, atlas, 'Arial', F, 0);
/** Lines a layout produced, read back off the glyphs' rows. */
function linesOf(layout: { glyphs: { y0: number }[] }): number {
return new Set(layout.glyphs.map((g) => Math.round(g.y0))).size;
}
const lay = (text: string, opts: Record<string, unknown>) =>
layoutText(text, atlas, 'Arial', { fontSizePx: F, lineHeight: LINE, ...opts } as never);
describe('TextOverflow', () => {
it('Visible keeps every line, however short the box', () => {
const l = lay('one\ntwo\nthree', { boxHeight: LINE, overflow: TextOverflow.Visible });
expect(linesOf(l)).toBe(3);
});
it('an unspecified overflow behaves as Visible', () => {
const l = lay('one\ntwo\nthree', { boxHeight: LINE });
expect(linesOf(l)).toBe(3);
});
it('Clip keeps only the lines the box has room for', () => {
expect(linesOf(lay('one\ntwo\nthree', { boxHeight: LINE * 2, overflow: TextOverflow.Clip }))).toBe(2);
expect(linesOf(lay('one\ntwo\nthree', { boxHeight: LINE * 3, overflow: TextOverflow.Clip }))).toBe(3);
});
it('a box too short for one line still shows one', () => {
// Nothing is not an answer a reader can act on, and it is what a rounding
// error in the box height would otherwise produce.
expect(linesOf(lay('one\ntwo', { boxHeight: 1, overflow: TextOverflow.Clip }))).toBe(1);
});
it('no box height means nothing can overflow one', () => {
expect(linesOf(lay('one\ntwo\nthree', { overflow: TextOverflow.Clip }))).toBe(3);
});
it('Ellipsis says there is more below, even when the last line fits', () => {
// The mark is about the DROPPED lines, not about this line being long —
// which is the distinction a reader needs and a width check cannot make.
const l = lay('one\ntwo\nthree', { boxHeight: LINE, overflow: TextOverflow.Ellipsis, boxWidth: 400 });
expect(linesOf(l)).toBe(1);
expect(l.width).toBeCloseTo(width('one…'), 5);
});
it('Clip drops the lines and adds no mark', () => {
const l = lay('one\ntwo\nthree', { boxHeight: LINE, overflow: TextOverflow.Clip, boxWidth: 400 });
expect(l.width).toBeCloseTo(width('one'), 5);
});
it('a single line too wide for the box is trimmed to fit, ellipsis included', () => {
const limit = width('abcde');
const l = lay('abcdefghij', { boxWidth: limit, overflow: TextOverflow.Ellipsis });
expect(l.width).toBeLessThanOrEqual(limit + 1e-6);
// Trimmed one glyph at a time, so the result is the widest that FITS —
// a proportional guess would leave visible slack or overshoot.
expect(l.width).toBeGreaterThan(limit - width('a') - width('…'));
});
it('Clip trims the same line without a mark, and keeps more of it', () => {
const limit = width('abcde');
const clipped = lay('abcdefghij', { boxWidth: limit, overflow: TextOverflow.Clip });
const ellipsed = lay('abcdefghij', { boxWidth: limit, overflow: TextOverflow.Ellipsis });
expect(clipped.width).toBeLessThanOrEqual(limit + 1e-6);
expect(clipped.width).toBeGreaterThan(ellipsed.width);
});
it('a line that fits is left exactly alone', () => {
const l = lay('abc', { boxWidth: width('abcdefgh'), overflow: TextOverflow.Ellipsis });
expect(l.width).toBeCloseTo(width('abc'), 5);
});
it('wrapping still happens first, and the box then decides how many survive', () => {
// maxWidth wraps 'aa aa aa' into three lines; a two-line box keeps two.
const l = lay('aa aa aa', {
maxWidth: width('aa') + 1, boxHeight: LINE * 2, overflow: TextOverflow.Clip,
});
expect(linesOf(l)).toBe(2);
});
it('rich text truncates by line, since a run carries its own size', () => {
const l = lay('one\n<b>two</b>\nthree', {
rich: true, boxHeight: LINE * 2, overflow: TextOverflow.Clip,
});
expect(linesOf(l)).toBe(2);
});
});
it.each([TextOverflow.Clip, TextOverflow.Ellipsis])('clips long text with linear glyph lookup work (mode=%s)', overflow => {
const atlas = makeAtlas();
const get = atlas.getGlyph.bind(atlas);
let lookups = 0;
atlas.getGlyph = (...args) => { lookups++; return get(...args); };
const text = 'A'.repeat(3000);
const result = layoutText(text, atlas, 'Arial', { fontSizePx: F, boxWidth: 30, overflow });
expect(result.width).toBeLessThanOrEqual(30);
expect(result.glyphs.length).toBeGreaterThan(0);
expect(lookups).toBeLessThan(text.length * 3);
});
it.each([-8, 0, 2.25])('matches whole-codepoint trimming with spaces and signed spacing (%s)', letterSpacing => {
const atlas = makeAtlas();
for (const line of ['A😀 B C测试 '.repeat(4), '😀😀😀abc', 'A\u2003B\u00a0C']) {
for (const overflow of [TextOverflow.Clip, TextOverflow.Ellipsis]) {
const measure = (s: string) => measureWidth(s, atlas, 'Arial', F, 0, letterSpacing);
for (const limit of [5, 13.5, 23, 50]) {
const tail = overflow === TextOverflow.Ellipsis ? '…' : '';
let expected = line;
if (measure(line) > limit) {
const chars = [...line]; expected = tail;
while (chars.length) {
chars.pop(); const candidate = chars.join('').trimEnd() + tail;
if (measure(candidate) <= limit) { expected = candidate; break; }
}
}
const opts = { fontSizePx: F, letterSpacing };
const actual = layoutText(line, atlas, 'Arial', { ...opts, boxWidth: limit, overflow });
const reference = layoutText(expected, atlas, 'Arial', opts);
expect(actual).toEqual(reference);
}
}
}
});
describe('TextOverflow.Shrink', () => {
const wideText = 'the quick brown fox';
const at = (size: number) => measureWidth(wideText, atlas, 'Arial', size, 0);
it('leaves text that already fits exactly as it was', () => {
const l = lay(wideText, { boxWidth: at(F) + 40, boxHeight: LINE * 2, overflow: TextOverflow.Shrink });
expect(l.fontSizePx).toBeUndefined();
expect(l.width).toBeCloseTo(at(F));
});
it('takes the largest whole size that fits the width, and not one more', () => {
const box = at(F) * 0.6;
const size = shrinkFontSize(wideText, atlas, 'Arial', { fontSizePx: F, lineHeight: LINE, boxWidth: box });
expect(size).toBeLessThan(F);
expect(Number.isInteger(size)).toBe(true);
expect(at(size)).toBeLessThanOrEqual(box + 1e-6);
expect(at(size + 1)).toBeGreaterThan(box);
});
it('lays the text out at that size, and says which size it was', () => {
const box = at(F) * 0.6;
const l = lay(wideText, { boxWidth: box, boxHeight: LINE, overflow: TextOverflow.Shrink });
expect(l.fontSizePx).toBeLessThan(F);
expect(l.width).toBeLessThanOrEqual(box + 1e-6);
// line height shrinks with the type: the block is one line of the smaller size
expect(l.lineHeight).toBeCloseTo(LINE * (l.fontSizePx! / F));
});
it('fits the height of wrapped text by making the lines smaller and more of them fit', () => {
const box = { boxWidth: at(F) * 0.5, maxWidth: at(F) * 0.5, boxHeight: LINE * 1.5 };
const l = lay(wideText, { ...box, overflow: TextOverflow.Shrink });
expect(l.lineHeight).toBeLessThanOrEqual(box.boxHeight + 1e-6);
expect(l.width).toBeLessThanOrEqual(box.boxWidth + 1e-6);
// and the plain, unshrunk text really did not fit — otherwise this proves nothing
expect(lay(wideText, { ...box, overflow: TextOverflow.Visible }).lineHeight).toBeGreaterThan(box.boxHeight);
});
it('is a no-op without a box, since nothing can overflow one', () => {
const l = lay(wideText, { overflow: TextOverflow.Shrink });
expect(l.fontSizePx).toBeUndefined();
});
it('never goes below one pixel: a box too small for anything shows the smallest text, not none', () => {
const l = lay(wideText, { boxWidth: 1, boxHeight: 1, overflow: TextOverflow.Shrink });
expect(l.fontSizePx).toBe(1);
expect(l.glyphs.length).toBeGreaterThan(0);
});
});
describe('TextOverflow.ResizeHeight', () => {
it('keeps every line however short the box, and reports the height of all of them', () => {
const l = lay('one\ntwo\nthree', { boxHeight: LINE, overflow: TextOverflow.ResizeHeight });
expect(linesOf(l)).toBe(3);
expect(l.lineHeight).toBeCloseTo(3 * LINE, 6);
});
it('does not trim a line that is wider than the box', () => {
const l = lay('a long line of text', { boxWidth: 20, overflow: TextOverflow.ResizeHeight });
expect(l.width).toBeCloseTo(width('a long line of text'), 6);
});
it('grows with wrapping: a narrower wrap width makes the block taller', () => {
const wide = lay('one two three four five six', { maxWidth: 400, overflow: TextOverflow.ResizeHeight });
const narrow = lay('one two three four five six', { maxWidth: 60, overflow: TextOverflow.ResizeHeight });
expect(narrow.lineHeight).toBeGreaterThan(wide.lineHeight);
});
});
describe('a laid-out line', () => {
it('says where it sits: its left edge, its width, and its baseline', () => {
const l = lay('ab\ncd', { align: 1, boxWidth: 100 });
expect(l.lines).toHaveLength(2);
expect(l.lines![0]!.baseline).toBeCloseTo(0, 6);
expect(l.lines![1]!.baseline).toBeCloseTo(-LINE, 6);
expect(l.lines![0]!.x).toBeCloseTo((100 - l.lines![0]!.width) / 2, 6);
});
});
describe('underline', () => {
const quads = (underline: boolean) => {
const out: number[] = [];
drawTextWith(atlas, (vertices) => { out.push(vertices.length); }, {
text: 'ab\ncd', fontFamily: 'Arial', fontSizePx: F, color: [1, 1, 1, 1], lineHeight: LINE, underline,
});
return out.reduce((a, b) => a + b, 0);
};
it('adds one bar to each line', () => {
const without = quads(false);
const withBars = quads(true);
// four glyphs and two bars, against four glyphs: the vertex data grows by one third
expect(withBars).toBeCloseTo(without * 6 / 4, 6);
});
});