pixi-silk 1.0.2 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/README.md +3 -2
- package/dist/SilkGraphics.d.ts +2 -1
- package/dist/SilkGraphics.js +6 -1
- package/dist/app.d.ts +8 -1
- package/dist/app.js +5 -1
- package/dist/batch.d.ts +2 -1
- package/dist/batch.js +4 -3
- package/dist/glass/GlassFilter.js +2 -1
- package/dist/shader-slot.js +3 -1
- package/dist/shader.js +4 -2
- package/dist/text/SilkText.d.ts +143 -6
- package/dist/text/SilkText.js +264 -35
- package/dist/text/atlas.d.ts +52 -2
- package/dist/text/atlas.js +231 -27
- package/dist/text/bidi.d.ts +36 -0
- package/dist/text/bidi.js +632 -0
- package/dist/text/cluster.d.ts +37 -0
- package/dist/text/cluster.js +277 -0
- package/dist/text/label.d.ts +20 -0
- package/dist/text/label.js +27 -1
- package/dist/text/layout.d.ts +162 -11
- package/dist/text/layout.js +541 -58
- package/dist/text/rich.d.ts +84 -0
- package/dist/text/rich.js +218 -0
- package/dist/text/shader.js +35 -5
- package/dist/text.d.ts +7 -4
- package/dist/text.js +6 -3
- package/dist/ui/textedit.d.ts +17 -2
- package/dist/ui/textedit.js +55 -18
- package/dist/webgl1/glsl100.js +123 -0
- package/dist/webgl1/hooks.js +137 -0
- package/dist/webgl1/programs.js +244 -0
- package/dist/webgl1.d.ts +41 -0
- package/dist/webgl1.js +104 -0
- package/package.json +14 -12
- package/skills/pixi-silk/SKILL.md +1 -0
- package/skills/pixi-silk-text/SKILL.md +57 -2
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
import { bidiClass } from "./bidi.js";
|
|
2
|
+
//#region src/text/cluster.ts
|
|
3
|
+
/**
|
|
4
|
+
* Clusters and line break opportunities for {@link layoutText}. A cluster is what SilkText measures
|
|
5
|
+
* and bakes as one glyph. It can be a character with its marks or an emoji sequence. It can also be
|
|
6
|
+
* a run of joined Arabic letters, or a word of a script that Canvas has to shape as a whole
|
|
7
|
+
* (Burmese, Thai, Khmer, the Indic scripts). Break opportunities let lines wrap where there are no spaces: between Chinese,
|
|
8
|
+
* Japanese and Korean characters, and between words of Thai, Burmese, Khmer and Lao.
|
|
9
|
+
*/
|
|
10
|
+
const Ctor = globalThis.Intl?.Segmenter;
|
|
11
|
+
let graphemeSeg = null;
|
|
12
|
+
let wordSeg = null;
|
|
13
|
+
const JOINING = /^[\p{Script=Arabic}\p{Script=Syriac}\p{Script=Nko}\p{Script=Mandaic}\p{Script=Mongolian}\p{Script=Adlam}\p{Script=Hanifi_Rohingya}]$/u;
|
|
14
|
+
const LETTER = /^\p{L}$/u;
|
|
15
|
+
/** Scripts Canvas has to shape a whole word of: reordered vowels, stacked consonants, conjuncts. */
|
|
16
|
+
const COMPLEX = [
|
|
17
|
+
["Myanmar", /^\p{Script=Myanmar}$/u],
|
|
18
|
+
["Thai", /^\p{Script=Thai}$/u],
|
|
19
|
+
["Lao", /^\p{Script=Lao}$/u],
|
|
20
|
+
["Khmer", /^\p{Script=Khmer}$/u],
|
|
21
|
+
["Tibetan", /^\p{Script=Tibetan}$/u],
|
|
22
|
+
["Devanagari", /^\p{Script=Devanagari}$/u],
|
|
23
|
+
["Bengali", /^\p{Script=Bengali}$/u],
|
|
24
|
+
["Gurmukhi", /^\p{Script=Gurmukhi}$/u],
|
|
25
|
+
["Gujarati", /^\p{Script=Gujarati}$/u],
|
|
26
|
+
["Oriya", /^\p{Script=Oriya}$/u],
|
|
27
|
+
["Tamil", /^\p{Script=Tamil}$/u],
|
|
28
|
+
["Telugu", /^\p{Script=Telugu}$/u],
|
|
29
|
+
["Kannada", /^\p{Script=Kannada}$/u],
|
|
30
|
+
["Malayalam", /^\p{Script=Malayalam}$/u],
|
|
31
|
+
["Sinhala", /^\p{Script=Sinhala}$/u],
|
|
32
|
+
["Javanese", /^\p{Script=Javanese}$/u],
|
|
33
|
+
["Balinese", /^\p{Script=Balinese}$/u],
|
|
34
|
+
["Tai_Tham", /^\p{Script=Tai_Tham}$/u]
|
|
35
|
+
];
|
|
36
|
+
const COMPLEX_ANY = /[\p{Script=Myanmar}\p{Script=Thai}\p{Script=Lao}\p{Script=Khmer}\p{Script=Tibetan}\p{Script=Devanagari}\p{Script=Bengali}\p{Script=Gurmukhi}\p{Script=Gujarati}\p{Script=Oriya}\p{Script=Tamil}\p{Script=Telugu}\p{Script=Kannada}\p{Script=Malayalam}\p{Script=Sinhala}\p{Script=Javanese}\p{Script=Balinese}\p{Script=Tai_Tham}]/u;
|
|
37
|
+
/** Scripts with no spaces between words: lines may break between Thai, Lao, Khmer and Burmese words. */
|
|
38
|
+
const NO_SPACES = /* @__PURE__ */ new Set([
|
|
39
|
+
"Myanmar",
|
|
40
|
+
"Thai",
|
|
41
|
+
"Lao",
|
|
42
|
+
"Khmer",
|
|
43
|
+
"Tibetan"
|
|
44
|
+
]);
|
|
45
|
+
/**
|
|
46
|
+
* Scripts whose grapheme clusters shape on their own: no vowel moves across a cluster. They are baked
|
|
47
|
+
* a cluster at a time, which reuses atlas cells, and only their line breaks use whole words.
|
|
48
|
+
*/
|
|
49
|
+
const BY_GRAPHEME = /* @__PURE__ */ new Set(["Thai", "Lao"]);
|
|
50
|
+
/** Text that needs more than one code point per glyph: marks, joiners, emoji sequences, cursive scripts. */
|
|
51
|
+
const NEEDS_CLUSTERS = /\u200d|\u200c|[\ufe00-\ufe0f]|[\u{1f3fb}-\u{1f3ff}]|[\p{M}\u{1f1e6}-\u{1f1ff}\p{Script=Arabic}\p{Script=Syriac}\p{Script=Nko}\p{Script=Mandaic}\p{Script=Mongolian}\p{Script=Adlam}\p{Script=Hanifi_Rohingya}\p{Script=Hebrew}]/u;
|
|
52
|
+
const CJK = /^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Bopomofo}\u3000-\u303f\u30fc\uff00-\uffef]$/u;
|
|
53
|
+
const HANGUL = /^\p{Script=Hangul}$/u;
|
|
54
|
+
const EMOJI = /^\p{Extended_Pictographic}$/u;
|
|
55
|
+
const DIGIT = /^\p{Nd}$/u;
|
|
56
|
+
const NO_START = new Set(Array.from("、。,.・:;?!゛゜ヽヾゝゞ々〻ー‐゠–〜~)〕]}〉》」』】〙〗〟⦆»ぁぃぅぇぉっゃゅょゎゕゖァィゥェォッャュョヮヵヶ)]},.!?:;%’”"));
|
|
57
|
+
const NO_END = new Set(Array.from("(〔[{〈《「『【〘〖〝⦅«([{‘“$£¥€#"));
|
|
58
|
+
const RIGHT_JOINING = [
|
|
59
|
+
1569,
|
|
60
|
+
1573,
|
|
61
|
+
1575,
|
|
62
|
+
1575,
|
|
63
|
+
1577,
|
|
64
|
+
1577,
|
|
65
|
+
1583,
|
|
66
|
+
1586,
|
|
67
|
+
1608,
|
|
68
|
+
1608,
|
|
69
|
+
1649,
|
|
70
|
+
1655,
|
|
71
|
+
1672,
|
|
72
|
+
1689,
|
|
73
|
+
1728,
|
|
74
|
+
1728,
|
|
75
|
+
1731,
|
|
76
|
+
1739,
|
|
77
|
+
1741,
|
|
78
|
+
1741,
|
|
79
|
+
1743,
|
|
80
|
+
1743,
|
|
81
|
+
1746,
|
|
82
|
+
1747,
|
|
83
|
+
1749,
|
|
84
|
+
1749,
|
|
85
|
+
1774,
|
|
86
|
+
1775,
|
|
87
|
+
1881,
|
|
88
|
+
1883,
|
|
89
|
+
1899,
|
|
90
|
+
1900,
|
|
91
|
+
1905,
|
|
92
|
+
1905,
|
|
93
|
+
1907,
|
|
94
|
+
1908,
|
|
95
|
+
1912,
|
|
96
|
+
1913,
|
|
97
|
+
2218,
|
|
98
|
+
2220,
|
|
99
|
+
2222,
|
|
100
|
+
2222,
|
|
101
|
+
2225,
|
|
102
|
+
2226,
|
|
103
|
+
2233,
|
|
104
|
+
2233,
|
|
105
|
+
1808,
|
|
106
|
+
1808,
|
|
107
|
+
1813,
|
|
108
|
+
1817,
|
|
109
|
+
1822,
|
|
110
|
+
1822,
|
|
111
|
+
1832,
|
|
112
|
+
1832,
|
|
113
|
+
1834,
|
|
114
|
+
1834,
|
|
115
|
+
1836,
|
|
116
|
+
1836,
|
|
117
|
+
1839,
|
|
118
|
+
1839,
|
|
119
|
+
1869,
|
|
120
|
+
1869
|
|
121
|
+
];
|
|
122
|
+
const ZWJ = "";
|
|
123
|
+
/** Longest joined Arabic run baked as one glyph, in letters. Longer runs are cut and joined with ZWJ. */
|
|
124
|
+
const MAX_JOINED = 24;
|
|
125
|
+
/** Longest word of a shaped script baked as one glyph, in grapheme clusters. */
|
|
126
|
+
const MAX_WORD = 16;
|
|
127
|
+
const ATTACH = /^(?:\u200d|\u200c|[\ufe00-\ufe0f]|[\u{1f3fb}-\u{1f3ff}]|[\p{M}\u{e0020}-\u{e007f}])$/u;
|
|
128
|
+
const inRange = (c, ranges) => {
|
|
129
|
+
for (let i = 0; i < ranges.length; i += 2) if (c >= ranges[i] && c <= ranges[i + 1]) return true;
|
|
130
|
+
return false;
|
|
131
|
+
};
|
|
132
|
+
const complexScript = (ch) => {
|
|
133
|
+
for (const [name, re] of COMPLEX) if (re.test(ch)) return name;
|
|
134
|
+
return null;
|
|
135
|
+
};
|
|
136
|
+
const first = (s) => String.fromCodePoint(s.codePointAt(0));
|
|
137
|
+
const lastBase = (s) => {
|
|
138
|
+
const chars = Array.from(s);
|
|
139
|
+
for (let i = chars.length - 1; i >= 0; i--) if (!ATTACH.test(chars[i])) return chars[i];
|
|
140
|
+
return chars[0] ?? "";
|
|
141
|
+
};
|
|
142
|
+
/** True for ideographs, kana, Korean syllables and emoji: characters a line may break beside. */
|
|
143
|
+
function isWide(ch) {
|
|
144
|
+
return CJK.test(ch) || HANGUL.test(ch) || EMOJI.test(ch);
|
|
145
|
+
}
|
|
146
|
+
/** True for characters a line must not start with: closing punctuation, small kana, `.` `,` `!` and the like. */
|
|
147
|
+
function noLineStart(ch) {
|
|
148
|
+
return NO_START.has(ch);
|
|
149
|
+
}
|
|
150
|
+
/** True for characters a line must not end with: opening brackets and currency signs. */
|
|
151
|
+
function noLineEnd(ch) {
|
|
152
|
+
return NO_END.has(ch);
|
|
153
|
+
}
|
|
154
|
+
/** Grapheme clusters of a text as [start, end) offsets. Uses `Intl.Segmenter` where the platform has it. */
|
|
155
|
+
function graphemes(text) {
|
|
156
|
+
const out = [];
|
|
157
|
+
if (Ctor) {
|
|
158
|
+
graphemeSeg ??= new Ctor(void 0, { granularity: "grapheme" });
|
|
159
|
+
for (const s of graphemeSeg.segment(text)) out.push([s.index, s.index + s.segment.length]);
|
|
160
|
+
return out;
|
|
161
|
+
}
|
|
162
|
+
let joined = false;
|
|
163
|
+
for (let i = 0; i < text.length;) {
|
|
164
|
+
const ch = first(text.slice(i));
|
|
165
|
+
const prev = out[out.length - 1];
|
|
166
|
+
if (prev && (joined || ATTACH.test(ch))) prev[1] = i + ch.length;
|
|
167
|
+
else out.push([i, i + ch.length]);
|
|
168
|
+
joined = ch === ZWJ;
|
|
169
|
+
i += ch.length;
|
|
170
|
+
}
|
|
171
|
+
return out;
|
|
172
|
+
}
|
|
173
|
+
/** Word boundaries of a text written without spaces. Null without `Intl.Segmenter`. */
|
|
174
|
+
function wordStarts(text) {
|
|
175
|
+
if (!Ctor || !COMPLEX_ANY.test(text)) return null;
|
|
176
|
+
wordSeg ??= new Ctor(void 0, { granularity: "word" });
|
|
177
|
+
const out = /* @__PURE__ */ new Set();
|
|
178
|
+
for (const s of wordSeg.segment(text)) out.add(s.index);
|
|
179
|
+
return out;
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Splits a paragraph into the clusters {@link layoutText} measures and draws, in reading order.
|
|
183
|
+
*
|
|
184
|
+
* - Plain text (Latin, Greek, Cyrillic, Chinese, Japanese, Korean) is one cluster per code point.
|
|
185
|
+
* - A character with its marks, an emoji with its modifiers and joiners, and a flag are one cluster.
|
|
186
|
+
* - Letters of a cursive script (Arabic, Syriac) stay together while they join, so Canvas shapes the
|
|
187
|
+
* run. A run breaks after a letter that does not join forward.
|
|
188
|
+
* - A word of a script that needs shaping (Burmese, Thai, Khmer, Lao, Tibetan, the Indic scripts and
|
|
189
|
+
* Sinhala) is one cluster. Vowels written before their consonant and stacked consonants then
|
|
190
|
+
* come out right.
|
|
191
|
+
*
|
|
192
|
+
* `breakBefore` marks where a line may break without a space. That is between Chinese and Japanese
|
|
193
|
+
* characters and Korean syllables unless `wordBreak` is `keep-all`, never before closing
|
|
194
|
+
* punctuation or small kana, never after opening brackets. It is also between words of Thai, Lao,
|
|
195
|
+
* Khmer and Burmese.
|
|
196
|
+
*/
|
|
197
|
+
function clusters(text, wordBreak = "normal") {
|
|
198
|
+
const out = [];
|
|
199
|
+
if (!NEEDS_CLUSTERS.test(text) && !COMPLEX_ANY.test(text)) for (let i = 0; i < text.length;) {
|
|
200
|
+
const ch = first(text.slice(i));
|
|
201
|
+
const type = bidiClass(ch.codePointAt(0));
|
|
202
|
+
out.push({
|
|
203
|
+
draw: ch,
|
|
204
|
+
start: i,
|
|
205
|
+
end: i + ch.length,
|
|
206
|
+
inner: [],
|
|
207
|
+
type,
|
|
208
|
+
breakBefore: false
|
|
209
|
+
});
|
|
210
|
+
i += ch.length;
|
|
211
|
+
}
|
|
212
|
+
else {
|
|
213
|
+
const words = wordStarts(text);
|
|
214
|
+
let cur = null;
|
|
215
|
+
let kind = "";
|
|
216
|
+
let open = false;
|
|
217
|
+
let count = 0;
|
|
218
|
+
for (const [a, b] of graphemes(text)) {
|
|
219
|
+
const g = text.slice(a, b);
|
|
220
|
+
const base = first(g);
|
|
221
|
+
const cp = base.codePointAt(0);
|
|
222
|
+
const joins = JOINING.test(base) && LETTER.test(base);
|
|
223
|
+
const script = joins || DIGIT.test(base) ? null : complexScript(base);
|
|
224
|
+
if (cur && kind === "join" && open && joins && count < MAX_JOINED) {
|
|
225
|
+
cur.draw += g;
|
|
226
|
+
cur.inner.push(a);
|
|
227
|
+
cur.end = b;
|
|
228
|
+
count++;
|
|
229
|
+
} else if (cur && kind === "join" && open && joins) {
|
|
230
|
+
cur.draw += ZWJ;
|
|
231
|
+
cur = {
|
|
232
|
+
draw: ZWJ + g,
|
|
233
|
+
start: a,
|
|
234
|
+
end: b,
|
|
235
|
+
inner: [],
|
|
236
|
+
type: bidiClass(cp),
|
|
237
|
+
breakBefore: false
|
|
238
|
+
};
|
|
239
|
+
out.push(cur);
|
|
240
|
+
count = 1;
|
|
241
|
+
} else if (cur && script && kind === script && !BY_GRAPHEME.has(script) && !words?.has(a) && count < MAX_WORD) {
|
|
242
|
+
cur.draw += g;
|
|
243
|
+
cur.inner.push(a);
|
|
244
|
+
cur.end = b;
|
|
245
|
+
count++;
|
|
246
|
+
} else {
|
|
247
|
+
const breakBefore = !!script && kind === script && NO_SPACES.has(script) && (words === null || words.has(a));
|
|
248
|
+
cur = {
|
|
249
|
+
draw: g,
|
|
250
|
+
start: a,
|
|
251
|
+
end: b,
|
|
252
|
+
inner: [],
|
|
253
|
+
type: bidiClass(cp),
|
|
254
|
+
breakBefore
|
|
255
|
+
};
|
|
256
|
+
out.push(cur);
|
|
257
|
+
kind = joins ? "join" : script ?? "";
|
|
258
|
+
count = 1;
|
|
259
|
+
}
|
|
260
|
+
open = joins && !g.includes("") && !(cp >= 1536 && cp <= 2303 && inRange(cp, RIGHT_JOINING));
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
for (let i = 1; i < out.length; i++) {
|
|
264
|
+
const c = out[i];
|
|
265
|
+
const a = lastBase(out[i - 1].draw);
|
|
266
|
+
const b = first(c.draw);
|
|
267
|
+
if (NO_START.has(b) || NO_END.has(a)) {
|
|
268
|
+
c.breakBefore = false;
|
|
269
|
+
continue;
|
|
270
|
+
}
|
|
271
|
+
if (c.breakBefore || wordBreak === "keep-all") continue;
|
|
272
|
+
if (isWide(a) && isWide(b)) c.breakBefore = true;
|
|
273
|
+
}
|
|
274
|
+
return out;
|
|
275
|
+
}
|
|
276
|
+
//#endregion
|
|
277
|
+
export { clusters, isWide, noLineEnd, noLineStart };
|
package/dist/text/label.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { LabelFactory } from "../ui/label.js";
|
|
2
2
|
import { SilkTextOptions } from "./SilkText.js";
|
|
3
|
+
import { RichInline, SilkRichTextOptions } from "./rich.js";
|
|
3
4
|
//#region src/text/label.d.ts
|
|
4
5
|
/**
|
|
5
6
|
* A label factory that makes {@link SilkText} labels, for widgets such as `ValuePill`. The widget's
|
|
@@ -16,4 +17,23 @@ import { SilkTextOptions } from "./SilkText.js";
|
|
|
16
17
|
* ```
|
|
17
18
|
*/
|
|
18
19
|
export declare function silkLabel(overrides?: Omit<SilkTextOptions, "text">): LabelFactory;
|
|
20
|
+
/**
|
|
21
|
+
* A label factory like {@link silkLabel} that makes {@link SilkRichText} labels, so a widget's
|
|
22
|
+
* text can hold icons: `pill.show('{up} 12%')`. `inlines` lists the objects by name. Pass functions
|
|
23
|
+
* that build them when a label may show one more than once, or when the widget makes several
|
|
24
|
+
* labels.
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* ```ts
|
|
28
|
+
* import { SilkGraphics } from 'pixi-silk';
|
|
29
|
+
* import { silkRichLabel } from 'pixi-silk/text';
|
|
30
|
+
* import { ValuePill } from 'pixi-silk/ui/pill';
|
|
31
|
+
*
|
|
32
|
+
* const up = () => new SilkGraphics().poly([0, 8, 5, 0, 10, 8]).fill(0x30d158);
|
|
33
|
+
* const pill = new ValuePill({ label: silkRichLabel({ up: { object: up, height: 'cap' } }) });
|
|
34
|
+
*
|
|
35
|
+
* pill.show('{up} 12%');
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
export declare function silkRichLabel(inlines: Record<string, RichInline>, overrides?: Omit<SilkRichTextOptions, "text" | "inlines">): LabelFactory;
|
|
19
39
|
//#endregion
|
package/dist/text/label.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { SilkText } from "./SilkText.js";
|
|
2
|
+
import { SilkRichText } from "./rich.js";
|
|
2
3
|
//#region src/text/label.ts
|
|
3
4
|
/** The parts of a PixiJS text style that a SilkText understands. */
|
|
4
5
|
function fromPixiStyle(style) {
|
|
@@ -34,5 +35,30 @@ function silkLabel(overrides = {}) {
|
|
|
34
35
|
...overrides
|
|
35
36
|
});
|
|
36
37
|
}
|
|
38
|
+
/**
|
|
39
|
+
* A label factory like {@link silkLabel} that makes {@link SilkRichText} labels, so a widget's
|
|
40
|
+
* text can hold icons: `pill.show('{up} 12%')`. `inlines` lists the objects by name. Pass functions
|
|
41
|
+
* that build them when a label may show one more than once, or when the widget makes several
|
|
42
|
+
* labels.
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* ```ts
|
|
46
|
+
* import { SilkGraphics } from 'pixi-silk';
|
|
47
|
+
* import { silkRichLabel } from 'pixi-silk/text';
|
|
48
|
+
* import { ValuePill } from 'pixi-silk/ui/pill';
|
|
49
|
+
*
|
|
50
|
+
* const up = () => new SilkGraphics().poly([0, 8, 5, 0, 10, 8]).fill(0x30d158);
|
|
51
|
+
* const pill = new ValuePill({ label: silkRichLabel({ up: { object: up, height: 'cap' } }) });
|
|
52
|
+
*
|
|
53
|
+
* pill.show('{up} 12%');
|
|
54
|
+
* ```
|
|
55
|
+
*/
|
|
56
|
+
function silkRichLabel(inlines, overrides = {}) {
|
|
57
|
+
return (style) => new SilkRichText({
|
|
58
|
+
...fromPixiStyle(style),
|
|
59
|
+
...overrides,
|
|
60
|
+
inlines
|
|
61
|
+
});
|
|
62
|
+
}
|
|
37
63
|
//#endregion
|
|
38
|
-
export { silkLabel };
|
|
64
|
+
export { silkLabel, silkRichLabel };
|
package/dist/text/layout.d.ts
CHANGED
|
@@ -1,12 +1,40 @@
|
|
|
1
|
+
import { TextDirection } from "./bidi.js";
|
|
2
|
+
import { WordBreak } from "./cluster.js";
|
|
1
3
|
//#region src/text/layout.d.ts
|
|
2
|
-
/**
|
|
3
|
-
|
|
4
|
+
/**
|
|
5
|
+
* Horizontal alignment of the lines of a text block. `start` and `end` follow the direction of each
|
|
6
|
+
* line's paragraph: `start` is left for left-to-right text and right for right-to-left text.
|
|
7
|
+
* `justify` stretches every wrapped line to the full width and aligns the last line of each
|
|
8
|
+
* paragraph to its start.
|
|
9
|
+
*/
|
|
10
|
+
export type TextAlign = "left" | "center" | "right" | "start" | "end" | "justify";
|
|
4
11
|
/** Widths of characters at the size being laid out, in local units. */
|
|
5
12
|
export interface TextMeasurer {
|
|
6
|
-
/**
|
|
13
|
+
/**
|
|
14
|
+
* Advance width of one character, without kerning or letter spacing. Right-to-left and cursive
|
|
15
|
+
* text also asks for whole runs of joined letters, and for their prefixes when placing carets.
|
|
16
|
+
*/
|
|
7
17
|
advance(char: string): number;
|
|
8
18
|
/** Extra space between two characters (negative pulls them together). */
|
|
9
19
|
kerning(a: string, b: string): number;
|
|
20
|
+
/**
|
|
21
|
+
* How far a character's ink reaches above and below the baseline. Optional. With it, lines grow
|
|
22
|
+
* to fit glyphs that reach past the font's ascent or descent (stacked Burmese, Thai or Vietnamese
|
|
23
|
+
* marks), so nothing overlaps the next line.
|
|
24
|
+
*/
|
|
25
|
+
ink?(char: string): {
|
|
26
|
+
ascent: number;
|
|
27
|
+
descent: number;
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
/** The box an inline object takes in a line, as {@link LayoutOptions.inlines} lists them. */
|
|
31
|
+
export interface InlineMetrics {
|
|
32
|
+
/** Advance width, margins included. */
|
|
33
|
+
width: number;
|
|
34
|
+
/** Height above the baseline. */
|
|
35
|
+
ascent: number;
|
|
36
|
+
/** Depth below the baseline. Negative when the box sits above the baseline. */
|
|
37
|
+
descent: number;
|
|
10
38
|
}
|
|
11
39
|
/** What {@link layoutText} needs besides the text. Sizes are in local units. */
|
|
12
40
|
export interface LayoutOptions {
|
|
@@ -18,22 +46,66 @@ export interface LayoutOptions {
|
|
|
18
46
|
letterSpacing?: number;
|
|
19
47
|
/** Distance between baselines. Default `ascent + descent`. */
|
|
20
48
|
lineHeight?: number;
|
|
21
|
-
/** Alignment of the lines inside the widest line. Default `
|
|
49
|
+
/** Alignment of the lines inside the widest line. Default `start`. */
|
|
22
50
|
align?: TextAlign;
|
|
51
|
+
/**
|
|
52
|
+
* Base direction of each paragraph. `auto` takes it from the paragraph's first strong character,
|
|
53
|
+
* so Arabic or Hebrew text runs right to left and Latin text left to right. Default `auto`.
|
|
54
|
+
*/
|
|
55
|
+
direction?: TextDirection;
|
|
56
|
+
/**
|
|
57
|
+
* Most lines to show. Text past the last one is dropped and the last line ends in `ellipsis`.
|
|
58
|
+
* 0 for no limit. Default 0.
|
|
59
|
+
*/
|
|
60
|
+
maxLines?: number;
|
|
61
|
+
/**
|
|
62
|
+
* Widest a line may be when `wordWrap` is off. A longer line is cut and ends in `ellipsis`. With
|
|
63
|
+
* `wordWrap` on, lines that cannot break narrower than `wordWrapWidth` are cut the same way when
|
|
64
|
+
* `maxWidth` or `maxLines` is set. Default no limit.
|
|
65
|
+
*/
|
|
66
|
+
maxWidth?: number;
|
|
67
|
+
/** What a cut line ends with. `null` cuts without a mark. Default `\u2026` (an ellipsis). */
|
|
68
|
+
ellipsis?: string | null;
|
|
69
|
+
/** Tab stops every this many space widths, from the start of the line. Default 8. */
|
|
70
|
+
tabSize?: number;
|
|
71
|
+
/** Lets `justify` stretch Arabic words with kashida (tatweel) before it widens spaces. Default true. */
|
|
72
|
+
kashida?: boolean;
|
|
23
73
|
/** Breaks lines longer than `wordWrapWidth` at spaces. Default false. */
|
|
24
74
|
wordWrap?: boolean;
|
|
25
75
|
/** Line width that `wordWrap` breaks at. Default 100. */
|
|
26
76
|
wordWrapWidth?: number;
|
|
27
77
|
/** Breaks words that do not fit on a line of their own. Default false. */
|
|
28
78
|
breakWords?: boolean;
|
|
29
|
-
/**
|
|
79
|
+
/**
|
|
80
|
+
* Gives the digits one width, so numbers do not jitter as they change. Each digit set gets its
|
|
81
|
+
* own width: ASCII, Arabic-Indic, Persian, Devanagari, Thai, Burmese and the others. Default false.
|
|
82
|
+
*/
|
|
30
83
|
tabularNumbers?: boolean;
|
|
31
84
|
/** Applies the font's kerning. Default true. */
|
|
32
85
|
kerning?: boolean;
|
|
86
|
+
/**
|
|
87
|
+
* Where lines may break without spaces: `normal` breaks between Chinese, Japanese and Korean
|
|
88
|
+
* characters, `keep-all` only at spaces. Thai, Burmese, Khmer and Lao break between words either
|
|
89
|
+
* way. Default `normal`.
|
|
90
|
+
*/
|
|
91
|
+
wordBreak?: WordBreak;
|
|
92
|
+
/**
|
|
93
|
+
* Grows the line box when a glyph's ink reaches past the font's ascent or descent, so tall
|
|
94
|
+
* stacks of marks are not cut or overlapped. Needs {@link TextMeasurer.ink}. Default true.
|
|
95
|
+
*/
|
|
96
|
+
fitInk?: boolean;
|
|
97
|
+
/**
|
|
98
|
+
* Boxes for inline objects. `{name}` in the text, with a name listed here, becomes one box that
|
|
99
|
+
* flows with the text like a character. Unlisted names stay text.
|
|
100
|
+
*/
|
|
101
|
+
inlines?: Record<string, InlineMetrics>;
|
|
33
102
|
}
|
|
34
103
|
/** A character placed by {@link layoutText}. */
|
|
35
104
|
export interface PlacedGlyph {
|
|
36
|
-
/**
|
|
105
|
+
/**
|
|
106
|
+
* What to draw: one code point. In text that needs the bidi pass, a base with its marks or a run
|
|
107
|
+
* of joined letters, so Arabic words shape. Brackets in right-to-left runs come mirrored.
|
|
108
|
+
*/
|
|
37
109
|
char: string;
|
|
38
110
|
/** Pen position: the left of its advance box, after alignment. */
|
|
39
111
|
x: number;
|
|
@@ -43,6 +115,21 @@ export interface PlacedGlyph {
|
|
|
43
115
|
line: number;
|
|
44
116
|
/** Offset of the character in the source text, in UTF-16 code units. */
|
|
45
117
|
index: number;
|
|
118
|
+
/** Name of the inline object this box stands for, when it is one. `char` is then U+FFFC. */
|
|
119
|
+
inline?: string;
|
|
120
|
+
}
|
|
121
|
+
/** A run of a line that goes one way, as {@link LayoutLine.runs} lists them. */
|
|
122
|
+
export interface LineRun {
|
|
123
|
+
/** Source offset of the run's first character. */
|
|
124
|
+
start: number;
|
|
125
|
+
/** Source offset after the run's last character. */
|
|
126
|
+
end: number;
|
|
127
|
+
/** Left edge of the run. */
|
|
128
|
+
left: number;
|
|
129
|
+
/** Right edge of the run. */
|
|
130
|
+
right: number;
|
|
131
|
+
/** True when the run reads right to left. */
|
|
132
|
+
rtl: boolean;
|
|
46
133
|
}
|
|
47
134
|
/** One line of a laid-out text. */
|
|
48
135
|
export interface LayoutLine {
|
|
@@ -71,11 +158,28 @@ export interface LayoutLine {
|
|
|
71
158
|
offsets: number[];
|
|
72
159
|
/** The x of the caret at each of `offsets`. Spaces past the line's edge hang beyond `width`. */
|
|
73
160
|
carets: number[];
|
|
161
|
+
/** True when the line's paragraph runs right to left. */
|
|
162
|
+
rtl: boolean;
|
|
163
|
+
/** True when the line was cut to fit `maxWidth` or `maxLines` and ends in the ellipsis. */
|
|
164
|
+
truncated: boolean;
|
|
165
|
+
/**
|
|
166
|
+
* The line's one-way runs in visual order, left to right. Set on lines that went through the bidi
|
|
167
|
+
* pass (they hold right-to-left text), absent on plain left-to-right lines.
|
|
168
|
+
*/
|
|
169
|
+
runs?: LineRun[];
|
|
170
|
+
/**
|
|
171
|
+
* Where a caret at each of `offsets` sits when it goes with the character after it, on lines with
|
|
172
|
+
* `runs`. Where the direction changes one offset has two places on screen: `carets` holds the one
|
|
173
|
+
* after the character before, `leads` the one before the character after.
|
|
174
|
+
*/
|
|
175
|
+
leads?: number[];
|
|
74
176
|
}
|
|
75
177
|
/** Result of {@link layoutText}. */
|
|
76
178
|
export interface TextLayout {
|
|
77
179
|
/** Every character with a position, spaces included. */
|
|
78
180
|
glyphs: PlacedGlyph[];
|
|
181
|
+
/** True when text was cut to fit `maxWidth` or `maxLines`. */
|
|
182
|
+
truncated: boolean;
|
|
79
183
|
/** The lines, top to bottom. Empty text has one empty line. */
|
|
80
184
|
lines: LayoutLine[];
|
|
81
185
|
/** Width of the widest line. */
|
|
@@ -89,10 +193,30 @@ export interface TextLayout {
|
|
|
89
193
|
/** Distance between baselines. */
|
|
90
194
|
lineHeight: number;
|
|
91
195
|
}
|
|
196
|
+
/** An inline object token in a text, as {@link inlineTokens} finds them. */
|
|
197
|
+
export interface InlineToken {
|
|
198
|
+
/** Offset of the opening brace. */
|
|
199
|
+
start: number;
|
|
200
|
+
/** Offset after the closing brace. */
|
|
201
|
+
end: number;
|
|
202
|
+
/** The name between the braces. */
|
|
203
|
+
name: string;
|
|
204
|
+
}
|
|
205
|
+
/** The `{name}` tokens of a text whose names `known` accepts, in order. Other braces stay text. */
|
|
206
|
+
export declare function inlineTokens(text: string, known: (name: string) => boolean): InlineToken[];
|
|
92
207
|
/**
|
|
93
208
|
* Lays out a block of text. Lines break at `\n` and, with `wordWrap`, at spaces. Each character gets
|
|
94
209
|
* its advance, kerning and letter spacing, then the lines are aligned. Widths come from `measure`,
|
|
95
210
|
* so the same layout works for any renderer.
|
|
211
|
+
*
|
|
212
|
+
* Paragraphs that hold right-to-left characters go through the bidi pass, and so does every
|
|
213
|
+
* paragraph when `direction` is `rtl`. Words wrap in reading order, then each line is reordered for
|
|
214
|
+
* display. Arabic and Hebrew read right to left, and numbers and Latin words inside them keep
|
|
215
|
+
* reading left to right.
|
|
216
|
+
*
|
|
217
|
+
* Text is measured and drawn in clusters (see {@link clusters}). Marks stay with their letter.
|
|
218
|
+
* Joined Arabic runs and words of Burmese, Thai and the Indic scripts are one glyph each, so Canvas
|
|
219
|
+
* shapes them. `{name}` tokens listed in `inlines` become boxes for inline objects.
|
|
96
220
|
*/
|
|
97
221
|
export declare function layoutText(text: string, options: LayoutOptions, measure: TextMeasurer): TextLayout;
|
|
98
222
|
/** Where a point lands in a {@link TextLayout}: the nearest caret position. */
|
|
@@ -106,8 +230,13 @@ export interface CaretHit {
|
|
|
106
230
|
* (a wrap). Pass it back to {@link caretRect} to draw the caret where the point was.
|
|
107
231
|
*/
|
|
108
232
|
upstream: boolean;
|
|
109
|
-
/**
|
|
233
|
+
/**
|
|
234
|
+
* True when the character under the point ends at `index`: the point is left of the caret, or
|
|
235
|
+
* right of it in right-to-left text.
|
|
236
|
+
*/
|
|
110
237
|
before: boolean;
|
|
238
|
+
/** True when the caret goes with the character after `index` (see {@link LayoutLine.leads}). */
|
|
239
|
+
leading: boolean;
|
|
111
240
|
}
|
|
112
241
|
/** A caret position in layout units: a vertical segment from `top` to `bottom` at `x`. */
|
|
113
242
|
export interface CaretRect {
|
|
@@ -137,10 +266,32 @@ export interface TextRect {
|
|
|
137
266
|
export declare function caretAtPoint(layout: TextLayout, x: number, y: number, isStop?: (index: number) => boolean): CaretHit;
|
|
138
267
|
/** The line a caret at `index` is on. At a wrap, `upstream` picks the end of the first line over the start of the next. */
|
|
139
268
|
export declare function lineOfIndex(layout: TextLayout, index: number, upstream?: boolean): number;
|
|
140
|
-
/**
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
269
|
+
/**
|
|
270
|
+
* The x of a caret at `index` on line `li`: the nearest caret stop at or before it. `leading` puts
|
|
271
|
+
* it before the character after it where the direction changes (see {@link LayoutLine.leads}).
|
|
272
|
+
*/
|
|
273
|
+
export declare function caretX(layout: TextLayout, li: number, index: number, leading?: boolean): number;
|
|
274
|
+
/** A caret stop: a source offset and the side it goes with, as {@link caretVisual} returns it. */
|
|
275
|
+
export interface CaretStop {
|
|
276
|
+
/** Source offset. */
|
|
277
|
+
index: number;
|
|
278
|
+
/** True when the caret goes with the character after `index` (see {@link LayoutLine.leads}). */
|
|
279
|
+
leading: boolean;
|
|
280
|
+
}
|
|
281
|
+
/**
|
|
282
|
+
* The caret stop one step left (`dir` -1) or right (1) on screen from `index`, on the same line.
|
|
283
|
+
* In a line that mixes directions this follows what the eye sees, not the order of the text. The
|
|
284
|
+
* arrow keys then move the way they point, and a caret can reach both places an offset has where
|
|
285
|
+
* the direction changes. Returns null on a line that runs left to right only, or at the line's edge:
|
|
286
|
+
* step through the text instead there. `isStop` filters the stops, for example to grapheme or word
|
|
287
|
+
* boundaries.
|
|
288
|
+
*/
|
|
289
|
+
export declare function caretVisual(layout: TextLayout, index: number, dir: number, upstream?: boolean, isStop?: (index: number) => boolean, leading?: boolean): CaretStop | null;
|
|
290
|
+
/**
|
|
291
|
+
* Where to draw a caret at `index`, in the layout's units. `leading` puts it before the character
|
|
292
|
+
* after it where the direction changes.
|
|
293
|
+
*/
|
|
294
|
+
export declare function caretRect(layout: TextLayout, index: number, upstream?: boolean, leading?: boolean): CaretRect;
|
|
144
295
|
/**
|
|
145
296
|
* Highlight boxes of the range `from` to `to`, one per line, the full height of each line box. A range
|
|
146
297
|
* that runs on past a newline gets a sliver of `newline` width at that line's end, so selected empty
|