harfbuzzjs 1.0.0-beta.1 → 1.0.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/dist/index.d.mts CHANGED
@@ -1,3 +1,6 @@
1
+ //#region src/helpers.d.ts
2
+ type ValueOf<T> = T[keyof T];
3
+ //#endregion
1
4
  //#region src/types.d.ts
2
5
  interface FontExtents {
3
6
  ascender: number;
@@ -15,6 +18,8 @@ interface GlyphInfo {
15
18
  codepoint: number;
16
19
  /** The cluster index of the glyph. */
17
20
  cluster: number;
21
+ /** Glyph flags, a combination of {@link GlyphFlag} values. */
22
+ flags: number;
18
23
  }
19
24
  interface GlyphPosition {
20
25
  /** The x advance of the glyph. */
@@ -26,22 +31,6 @@ interface GlyphPosition {
26
31
  /** The y offset of the glyph. */
27
32
  yOffset: number;
28
33
  }
29
- interface JsonGlyph {
30
- /** The glyph ID. */
31
- g: number;
32
- /** The cluster ID. */
33
- cl: number;
34
- /** Advance width (width to advance after this glyph is painted). */
35
- ax: number;
36
- /** Advance height (height to advance after this glyph is painted). */
37
- ay: number;
38
- /** X displacement (adjustment in X dimension when painting this glyph). */
39
- dx: number;
40
- /** Y displacement (adjustment in Y dimension when painting this glyph). */
41
- dy: number;
42
- /** Glyph flags, a combination of {@link GlyphFlag} values. */
43
- fl: number;
44
- }
45
34
  interface SvgPathCommand {
46
35
  type: string;
47
36
  values: number[];
@@ -56,9 +45,9 @@ interface NameEntry {
56
45
  language: string;
57
46
  }
58
47
  interface FeatureNameIds {
59
- uiLabelNameId: number | null;
60
- uiTooltipTextNameId: number | null;
61
- sampleTextNameId: number | null;
48
+ uiLabelNameId?: number;
49
+ uiTooltipTextNameId?: number;
50
+ sampleTextNameId?: number;
62
51
  paramUiLabelNameIds: number[];
63
52
  }
64
53
  interface TraceEntry {
@@ -81,7 +70,7 @@ declare const GlyphFlag: {
81
70
  readonly SAFE_TO_INSERT_TATWEEL: 4;
82
71
  readonly DEFINED: 7;
83
72
  };
84
- type GlyphFlag = (typeof GlyphFlag)[keyof typeof GlyphFlag];
73
+ type GlyphFlag = ValueOf<typeof GlyphFlag>;
85
74
  //#endregion
86
75
  //#region src/blob.d.ts
87
76
  /**
@@ -104,7 +93,7 @@ declare const GlyphClass: {
104
93
  readonly MARK: 3;
105
94
  readonly COMPONENT: 4;
106
95
  };
107
- type GlyphClass = (typeof GlyphClass)[keyof typeof GlyphClass];
96
+ type GlyphClass = ValueOf<typeof GlyphClass>;
108
97
  /**
109
98
  * An object representing a {@link https://harfbuzz.github.io/harfbuzz-hb-face.html | HarfBuzz face}.
110
99
  * A face represents a single face in a binary font file and is the
@@ -188,9 +177,9 @@ declare class Face {
188
177
  * Get the name IDs of the specified feature.
189
178
  * @param table The table to query, either "GSUB" or "GPOS".
190
179
  * @param featureIndex The index of the feature to query.
191
- * @returns An object with name IDs, or null if not found.
180
+ * @returns An object with name IDs, or undefined if not found.
192
181
  */
193
- getFeatureNameIds(table: string, featureIndex: number): FeatureNameIds | null;
182
+ getFeatureNameIds(table: string, featureIndex: number): FeatureNameIds | undefined;
194
183
  }
195
184
  //#endregion
196
185
  //#region src/font-funcs.d.ts
@@ -206,15 +195,15 @@ declare class FontFuncs {
206
195
  /**
207
196
  * Set the font's glyph extents function.
208
197
  * @param func The callback receives a Font and glyph ID. It should return
209
- * an object with xBearing, yBearing, width, and height, or null on failure.
198
+ * an object with xBearing, yBearing, width, and height, or undefined on failure.
210
199
  */
211
- setGlyphExtentsFunc(func: (font: Font, glyph: number) => GlyphExtents | null): void;
200
+ setGlyphExtentsFunc(func: (font: Font, glyph: number) => GlyphExtents | undefined): void;
212
201
  /**
213
202
  * Set the font's glyph from name function.
214
203
  * @param func The callback receives a Font and glyph name. It should return
215
- * the glyph ID, or null on failure.
204
+ * the glyph ID, or undefined on failure.
216
205
  */
217
- setGlyphFromNameFunc(func: (font: Font, name: string) => number | null): void;
206
+ setGlyphFromNameFunc(func: (font: Font, name: string) => number | undefined): void;
218
207
  /**
219
208
  * Set the font's glyph horizontal advance function.
220
209
  * @param func The callback receives a Font and glyph ID. It should return
@@ -230,15 +219,15 @@ declare class FontFuncs {
230
219
  /**
231
220
  * Set the font's glyph horizontal origin function.
232
221
  * @param func The callback receives a Font and glyph ID. It should return
233
- * the [x, y] horizontal origin of the glyph, or null on failure.
222
+ * the [x, y] horizontal origin of the glyph, or undefined on failure.
234
223
  */
235
- setGlyphHOriginFunc(func: (font: Font, glyph: number) => [number, number] | null): void;
224
+ setGlyphHOriginFunc(func: (font: Font, glyph: number) => [number, number] | undefined): void;
236
225
  /**
237
226
  * Set the font's glyph vertical origin function.
238
227
  * @param func The callback receives a Font and glyph ID. It should return
239
- * the [x, y] vertical origin of the glyph, or null on failure.
228
+ * the [x, y] vertical origin of the glyph, or undefined on failure.
240
229
  */
241
- setGlyphVOriginFunc(func: (font: Font, glyph: number) => [number, number] | null): void;
230
+ setGlyphVOriginFunc(func: (font: Font, glyph: number) => [number, number] | undefined): void;
242
231
  /**
243
232
  * Set the font's glyph horizontal kerning function.
244
233
  * @param func The callback receives a Font, first glyph ID, and second glyph ID.
@@ -248,33 +237,74 @@ declare class FontFuncs {
248
237
  /**
249
238
  * Set the font's glyph name function.
250
239
  * @param func The callback receives a Font and glyph ID. It should return
251
- * the name of the glyph, or null on failure.
240
+ * the name of the glyph, or undefined on failure.
252
241
  */
253
- setGlyphNameFunc(func: (font: Font, glyph: number) => string | null): void;
242
+ setGlyphNameFunc(func: (font: Font, glyph: number) => string | undefined): void;
254
243
  /**
255
244
  * Set the font's nominal glyph function.
256
245
  * @param func The callback receives a Font and unicode code point. It should
257
- * return the nominal glyph of the unicode, or null on failure.
246
+ * return the nominal glyph of the unicode, or undefined on failure.
258
247
  */
259
- setNominalGlyphFunc(func: (font: Font, unicode: number) => number | null): void;
248
+ setNominalGlyphFunc(func: (font: Font, unicode: number) => number | undefined): void;
260
249
  /**
261
250
  * Set the font's variation glyph function.
262
251
  * @param func The callback receives a Font, unicode code point, and variation
263
- * selector. It should return the variation glyph, or null on failure.
252
+ * selector. It should return the variation glyph, or undefined on failure.
264
253
  */
265
- setVariationGlyphFunc(func: (font: Font, unicode: number, variationSelector: number) => number | null): void;
254
+ setVariationGlyphFunc(func: (font: Font, unicode: number, variationSelector: number) => number | undefined): void;
266
255
  /**
267
256
  * Set the font's horizontal extents function.
268
257
  * @param func The callback receives a Font. It should return an object with
269
- * ascender, descender, and lineGap, or null on failure.
258
+ * ascender, descender, and lineGap, or undefined on failure.
270
259
  */
271
- setFontHExtentsFunc(func: (font: Font) => FontExtents | null): void;
260
+ setFontHExtentsFunc(func: (font: Font) => FontExtents | undefined): void;
272
261
  /**
273
262
  * Set the font's vertical extents function.
274
263
  * @param func The callback receives a Font. It should return an object with
275
- * ascender, descender, and lineGap, or null on failure.
264
+ * ascender, descender, and lineGap, or undefined on failure.
265
+ */
266
+ setFontVExtentsFunc(func: (font: Font) => FontExtents | undefined): void;
267
+ }
268
+ //#endregion
269
+ //#region src/variation.d.ts
270
+ /**
271
+ * A {@link https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-variation-t | HarfBuzz variation}.
272
+ *
273
+ * Data type for holding variation data. Registered OpenType variation-axis
274
+ * tags are listed in
275
+ * {@link https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg | OpenType Axis Tag Registry}.
276
+ */
277
+ declare class Variation {
278
+ /** The tag of the variation-axis name. */
279
+ tag: string;
280
+ /** The value of the variation axis. */
281
+ value: number;
282
+ constructor(tag: string, value?: number);
283
+ /**
284
+ * Parses a string into a Variation.
285
+ *
286
+ * The format for specifying variation settings follows. All valid CSS
287
+ * font-variation-settings values other than `normal` and `inherited` are
288
+ * also accepted, though, not documented below.
289
+ *
290
+ * The format is a tag, optionally followed by an equals sign, followed by a
291
+ * number. For example `wght=500`, or `slnt=-7.5`.
292
+ *
293
+ * @param str The string to parse.
294
+ * @returns A Variation, or undefined if the string is not a valid variation.
295
+ */
296
+ static fromString(str: string): Variation | undefined;
297
+ /**
298
+ * Converts the variation to a string in the format understood by
299
+ * {@link Variation.fromString}.
300
+ *
301
+ * Note that the string won't include any whitespace.
302
+ *
303
+ * @returns The variation string.
276
304
  */
277
- setFontVExtentsFunc(func: (font: Font) => FontExtents | null): void;
305
+ toString(): string;
306
+ /** @internal Write this variation into the given hb_variation_t pointer. */
307
+ writeTo(ptr: number): void;
278
308
  }
279
309
  //#endregion
280
310
  //#region src/font.d.ts
@@ -335,27 +365,62 @@ declare class Font {
335
365
  /**
336
366
  * Return glyph horizontal origin.
337
367
  * @param glyphId ID of the requested glyph in the font.
338
- * @returns [x, y] origin coordinates, or null if not available.
368
+ * @returns [x, y] origin coordinates, or undefined if not available.
339
369
  */
340
- glyphHOrigin(glyphId: number): [number, number] | null;
370
+ glyphHOrigin(glyphId: number): [number, number] | undefined;
341
371
  /**
342
372
  * Return glyph vertical origin.
343
373
  * @param glyphId ID of the requested glyph in the font.
344
- * @returns [x, y] origin coordinates, or null if not available.
374
+ * @returns [x, y] origin coordinates, or undefined if not available.
345
375
  */
346
- glyphVOrigin(glyphId: number): [number, number] | null;
376
+ glyphVOrigin(glyphId: number): [number, number] | undefined;
347
377
  /**
348
378
  * Return glyph extents.
349
379
  * @param glyphId ID of the requested glyph in the font.
350
- * @returns An object with xBearing, yBearing, width, and height, or null.
380
+ * @returns An object with xBearing, yBearing, width, and height, or undefined.
381
+ */
382
+ glyphExtents(glyphId: number): GlyphExtents | undefined;
383
+ /**
384
+ * Fetches the glyph ID for a Unicode code point in the specified
385
+ * font, with an optional variation selector.
386
+ *
387
+ * If `variationSelector` is 0, it is equivalent to
388
+ * {@link Font.nominalGlyph}; otherwise it is equivalent to
389
+ * {@link Font.variationGlyph}.
390
+ *
391
+ * @param unicode The Unicode code point to query.
392
+ * @param variationSelector A variation-selector code point.
393
+ * @returns The glyph ID, or undefined if not found.
351
394
  */
352
- glyphExtents(glyphId: number): GlyphExtents | null;
395
+ glyph(unicode: number, variationSelector?: number): number | undefined;
396
+ /**
397
+ * Fetches the nominal glyph ID for a Unicode code point in the
398
+ * specified font.
399
+ *
400
+ * This version of the function should not be used to fetch glyph IDs
401
+ * for code points modified by variation selectors. For variation-selector
402
+ * support, use {@link Font.variationGlyph} or {@link Font.glyph}.
403
+ *
404
+ * @param unicode The Unicode code point to query.
405
+ * @returns The glyph ID, or undefined if not found.
406
+ */
407
+ nominalGlyph(unicode: number): number | undefined;
408
+ /**
409
+ * Fetches the glyph ID for a Unicode code point when followed by
410
+ * by the specified variation-selector code point, in the specified
411
+ * font.
412
+ *
413
+ * @param unicode The Unicode code point to query.
414
+ * @param variationSelector The variation-selector code point to query.
415
+ * @returns The glyph ID, or undefined if not found.
416
+ */
417
+ variationGlyph(unicode: number, variationSelector: number): number | undefined;
353
418
  /**
354
419
  * Return glyph ID from name.
355
420
  * @param name Name of the requested glyph in the font.
356
- * @returns The glyph ID, or null if not found.
421
+ * @returns The glyph ID, or undefined if not found.
357
422
  */
358
- glyphFromName(name: string): number | null;
423
+ glyphFromName(name: string): number | undefined;
359
424
  /**
360
425
  * Return a glyph as a JSON path string
361
426
  * based on format described on https://svgwg.org/specs/paths/#InterfaceSVGPathSegment
@@ -371,10 +436,15 @@ declare class Font {
371
436
  */
372
437
  setScale(xScale: number, yScale: number): void;
373
438
  /**
374
- * Set the font's variations.
375
- * @param variations Dictionary of variations to set.
439
+ * Applies a list of font-variation settings to a font.
440
+ *
441
+ * Note that this overrides all existing variations set on the font.
442
+ * Axes not included in `variations` will be effectively set to their
443
+ * default values.
444
+ *
445
+ * @param variations Array of variation settings to apply.
376
446
  */
377
- setVariations(variations: Record<string, number>): void;
447
+ setVariations(variations: Variation[]): void;
378
448
  /** Set the font's font functions. */
379
449
  setFuncs(fontFuncs: FontFuncs): void;
380
450
  }
@@ -385,7 +455,7 @@ declare const BufferContentType: {
385
455
  readonly UNICODE: 1;
386
456
  readonly GLYPHS: 2;
387
457
  };
388
- type BufferContentType = (typeof BufferContentType)[keyof typeof BufferContentType];
458
+ type BufferContentType = ValueOf<typeof BufferContentType>;
389
459
  declare const BufferSerializeFlag: {
390
460
  readonly DEFAULT: 0;
391
461
  readonly NO_CLUSTERS: 1;
@@ -396,7 +466,7 @@ declare const BufferSerializeFlag: {
396
466
  readonly NO_ADVANCES: 32;
397
467
  readonly DEFINED: 63;
398
468
  };
399
- type BufferSerializeFlag = (typeof BufferSerializeFlag)[keyof typeof BufferSerializeFlag];
469
+ type BufferSerializeFlag = ValueOf<typeof BufferSerializeFlag>;
400
470
  declare const BufferFlag: {
401
471
  readonly DEFAULT: 0;
402
472
  readonly BOT: 1;
@@ -409,7 +479,7 @@ declare const BufferFlag: {
409
479
  readonly PRODUCE_SAFE_TO_INSERT_TATWEEL: 128;
410
480
  readonly DEFINED: 255;
411
481
  };
412
- type BufferFlag = (typeof BufferFlag)[keyof typeof BufferFlag];
482
+ type BufferFlag = ValueOf<typeof BufferFlag>;
413
483
  declare const Direction: {
414
484
  readonly INVALID: 0;
415
485
  readonly LTR: 4;
@@ -417,13 +487,21 @@ declare const Direction: {
417
487
  readonly TTB: 6;
418
488
  readonly BTT: 7;
419
489
  };
420
- type Direction = (typeof Direction)[keyof typeof Direction];
490
+ type Direction = ValueOf<typeof Direction>;
491
+ declare const ClusterLevel: {
492
+ readonly MONOTONE_GRAPHEMES: 0;
493
+ readonly MONOTONE_CHARACTERS: 1;
494
+ readonly CHARACTERS: 2;
495
+ readonly GRAPHEMES: 3;
496
+ readonly DEFAULT: 0;
497
+ };
498
+ type ClusterLevel = ValueOf<typeof ClusterLevel>;
421
499
  declare const BufferSerializeFormat: {
422
500
  readonly INVALID: 0;
423
501
  readonly TEXT: number;
424
502
  readonly JSON: number;
425
503
  };
426
- type BufferSerializeFormat = (typeof BufferSerializeFormat)[keyof typeof BufferSerializeFormat];
504
+ type BufferSerializeFormat = ValueOf<typeof BufferSerializeFormat>;
427
505
  /**
428
506
  * An object representing a {@link https://harfbuzz.github.io/harfbuzz-hb-buffer.html | HarfBuzz buffer}.
429
507
  * A buffer holds the input text and its properties before shaping, and the
@@ -431,23 +509,37 @@ type BufferSerializeFormat = (typeof BufferSerializeFormat)[keyof typeof BufferS
431
509
  */
432
510
  declare class Buffer {
433
511
  readonly ptr: number;
434
- constructor();
435
- /** @internal Wrap an existing buffer pointer. */
436
- constructor(existingPtr: number);
512
+ /**
513
+ * @param existingPtr @internal Wrap an existing buffer pointer.
514
+ */
515
+ constructor(existingPtr?: number);
516
+ /**
517
+ * Appends a character with the Unicode value of `codePoint` to the buffer,
518
+ * and gives it the initial cluster value of `cluster`. Clusters can be any
519
+ * thing the client wants, they are usually used to refer to the index of the
520
+ * character in the input text stream and are output in the `cluster` field
521
+ * of {@link GlyphInfo}.
522
+ *
523
+ * This function does not check the validity of `codePoint`, it is up to the
524
+ * caller to ensure it is a valid Unicode code point.
525
+ * @param codePoint A Unicode code point.
526
+ * @param cluster The cluster value of `codePoint`.
527
+ */
528
+ add(codePoint: number, cluster: number): void;
437
529
  /**
438
530
  * Add text to the buffer.
439
531
  * @param text Text to be added to the buffer.
440
532
  * @param itemOffset The offset of the first character to add to the buffer.
441
- * @param itemLength The number of characters to add to the buffer, or null for the end of text.
533
+ * @param itemLength The number of characters to add to the buffer, or omit for the end of text.
442
534
  */
443
- addText(text: string, itemOffset?: number, itemLength?: number | null): void;
535
+ addText(text: string, itemOffset?: number, itemLength?: number): void;
444
536
  /**
445
537
  * Add code points to the buffer.
446
538
  * @param codePoints Array of code points to be added to the buffer.
447
539
  * @param itemOffset The offset of the first code point to add to the buffer.
448
- * @param itemLength The number of code points to add to the buffer, or null for the end of the array.
540
+ * @param itemLength The number of code points to add to the buffer, or omit for the end of the array.
449
541
  */
450
- addCodePoints(codePoints: number[], itemOffset?: number, itemLength?: number | null): void;
542
+ addCodePoints(codePoints: number[], itemOffset?: number, itemLength?: number): void;
451
543
  /**
452
544
  * Set buffer script, language and direction.
453
545
  *
@@ -478,9 +570,9 @@ declare class Buffer {
478
570
  * Set the HarfBuzz clustering level.
479
571
  *
480
572
  * Affects the cluster values returned from shaping.
481
- * @param level Clustering level. See the HarfBuzz manual chapter on Clusters.
573
+ * @param level A {@link ClusterLevel} value. See the HarfBuzz manual chapter on Clusters.
482
574
  */
483
- setClusterLevel(level: number): void;
575
+ setClusterLevel(level: ClusterLevel): void;
484
576
  /** Reset the buffer to its initial status. */
485
577
  reset(): void;
486
578
  /**
@@ -525,26 +617,108 @@ declare class Buffer {
525
617
  updateGlyphPositions(positions: GlyphPosition[]): void;
526
618
  /**
527
619
  * Serialize the buffer contents to a string.
528
- * @param font The font to use for serialization.
529
- * @param start The starting index of the glyphs to serialize.
530
- * @param end The ending index of the glyphs to serialize.
531
- * @param format The {@link BufferSerializeFormat} to serialize the buffer contents to.
532
- * @param flags A combination of {@link BufferSerializeFlag} values (OR them together).
533
- *
620
+ * @param options Serialization options:
621
+ * - `font`: the font to use for serialization;
622
+ * - `start`: the starting index of the glyphs (default `0`);
623
+ * - `end`: the ending index of the glyphs (default end of buffer);
624
+ * - `format`: a {@link BufferSerializeFormat} value (default `TEXT`);
625
+ * - `flags`: a combination of {@link BufferSerializeFlag} values (default `0`).
534
626
  * @returns The serialized buffer contents.
535
627
  */
536
- serialize(font?: Font | null, start?: number, end?: number | null, format?: BufferSerializeFormat, flags?: number): string;
628
+ serialize(options?: {
629
+ font?: Font;
630
+ start?: number;
631
+ end?: number;
632
+ format?: BufferSerializeFormat;
633
+ flags?: number;
634
+ }): string;
537
635
  /**
538
636
  * Return the buffer content type.
539
637
  *
540
638
  * @returns The buffer content type as a {@link BufferContentType} value.
541
639
  */
542
640
  getContentType(): BufferContentType;
641
+ }
642
+ //#endregion
643
+ //#region src/feature.d.ts
644
+ /**
645
+ * A {@link https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-t | HarfBuzz feature}.
646
+ *
647
+ * The structure that holds information about requested feature application.
648
+ * The feature will be applied with the given value to all glyphs which are in
649
+ * clusters between {@link Feature.start} (inclusive) and {@link Feature.end}
650
+ * (exclusive). Setting `start` to `0` and `end` to `0xffffffff` specifies that
651
+ * the feature always applies to the entire buffer.
652
+ */
653
+ declare class Feature {
543
654
  /**
544
- * Return the buffer contents as a JSON object.
545
- * @returns An array of {@link JsonGlyph} objects.
655
+ * Special setting for {@link Feature.start} to apply the feature from the
656
+ * start of the buffer.
657
+ */
658
+ static readonly GLOBAL_START = 0;
659
+ /**
660
+ * Special setting for {@link Feature.end} to apply the feature from to the
661
+ * end of the buffer.
662
+ */
663
+ static readonly GLOBAL_END = 4294967295;
664
+ /** The tag of the feature. */
665
+ tag: string;
666
+ /**
667
+ * The value of the feature. `0` disables the feature, non-zero (usually `1`)
668
+ * enables the feature. For features implemented as lookup type 3 (like
669
+ * `salt`) the value is a one-based index into the alternates.
670
+ */
671
+ value: number;
672
+ /** The cluster to start applying this feature setting (inclusive). */
673
+ start: number;
674
+ /** The cluster to end applying this feature setting (exclusive). */
675
+ end: number;
676
+ constructor(tag: string, value?: number, start?: number, end?: number);
677
+ /**
678
+ * Parses a string into a Feature.
679
+ *
680
+ * The format for specifying feature strings follows. All valid CSS
681
+ * font-feature-settings values other than `normal` and the global values are
682
+ * also accepted, though not documented below. CSS string escapes are not
683
+ * supported.
684
+ *
685
+ * The range indices refer to the positions between Unicode characters. The
686
+ * position before the first character is always 0.
687
+ *
688
+ * The format is Python-esque. Here is how it all works:
689
+ *
690
+ * | Syntax | Value | Start | End | Meaning |
691
+ * | ------------- | ----- | ----- | --- | -------------------------------- |
692
+ * | `kern` | 1 | 0 | ∞ | Turn feature on |
693
+ * | `+kern` | 1 | 0 | ∞ | Turn feature on |
694
+ * | `-kern` | 0 | 0 | ∞ | Turn feature off |
695
+ * | `kern=0` | 0 | 0 | ∞ | Turn feature off |
696
+ * | `kern=1` | 1 | 0 | ∞ | Turn feature on |
697
+ * | `aalt=2` | 2 | 0 | ∞ | Choose 2nd alternate |
698
+ * | `kern[]` | 1 | 0 | ∞ | Turn feature on |
699
+ * | `kern[:]` | 1 | 0 | ∞ | Turn feature on |
700
+ * | `kern[5:]` | 1 | 5 | ∞ | Turn feature on, partial |
701
+ * | `kern[:5]` | 1 | 0 | 5 | Turn feature on, partial |
702
+ * | `kern[3:5]` | 1 | 3 | 5 | Turn feature on, range |
703
+ * | `kern[3]` | 1 | 3 | 3+1 | Turn feature on, single char |
704
+ * | `aalt[3:5]=2` | 2 | 3 | 5 | Turn 2nd alternate on for range |
705
+ *
706
+ * @param str The string to parse.
707
+ * @returns A Feature, or undefined if the string is not a valid feature.
708
+ */
709
+ static fromString(str: string): Feature | undefined;
710
+ /**
711
+ * Converts the feature to a string in the format understood by
712
+ * {@link Feature.fromString}.
713
+ *
714
+ * Note that the feature value will be omitted if it is `1`, but the string
715
+ * won't include any whitespace.
716
+ *
717
+ * @returns The feature string.
546
718
  */
547
- json(): JsonGlyph[];
719
+ toString(): string;
720
+ /** @internal Write this feature into the given hb_feature_t pointer. */
721
+ writeTo(ptr: number): void;
548
722
  }
549
723
  //#endregion
550
724
  //#region src/shape.d.ts
@@ -553,7 +727,7 @@ declare const TracePhase: {
553
727
  readonly GSUB: 1;
554
728
  readonly GPOS: 2;
555
729
  };
556
- type TracePhase = (typeof TracePhase)[keyof typeof TracePhase];
730
+ type TracePhase = ValueOf<typeof TracePhase>;
557
731
  /**
558
732
  * Shape a buffer with a given font.
559
733
  *
@@ -563,9 +737,9 @@ type TracePhase = (typeof TracePhase)[keyof typeof TracePhase];
563
737
  * @param font The Font to shape with.
564
738
  * @param buffer The Buffer containing text to shape, suitably prepared
565
739
  * (text added, segment properties set).
566
- * @param features A string of comma-separated OpenType features to apply.
740
+ * @param features An array of {@link Feature} values to apply.
567
741
  */
568
- declare function shape(font: Font, buffer: Buffer, features?: string): void;
742
+ declare function shape(font: Font, buffer: Buffer, features?: Feature[]): void;
569
743
  /**
570
744
  * Shape a buffer with a given font, returning a JSON trace of the shaping process.
571
745
  *
@@ -574,12 +748,12 @@ declare function shape(font: Font, buffer: Buffer, features?: string): void;
574
748
  *
575
749
  * @param font The Font to shape with.
576
750
  * @param buffer The Buffer containing text to shape, suitably prepared.
577
- * @param features A string of comma-separated OpenType features to apply.
751
+ * @param features An array of {@link Feature} values to apply.
578
752
  * @param stop_at A lookup ID at which to terminate shaping.
579
753
  * @param stop_phase The {@link TracePhase} at which to stop shaping.
580
754
  * @returns An array of trace entries, each with a message, serialized glyphs, and phase info.
581
755
  */
582
- declare function shapeWithTrace(font: Font, buffer: Buffer, features: string, stop_at: number, stop_phase: TracePhase): TraceEntry[];
756
+ declare function shapeWithTrace(font: Font, buffer: Buffer, features: Feature[], stop_at: number, stop_phase: TracePhase): TraceEntry[];
583
757
  /**
584
758
  * Return the HarfBuzz version.
585
759
  * @returns An object with major, minor, and micro version numbers.
@@ -607,4 +781,4 @@ declare function otTagToScript(tag: string): string;
607
781
  */
608
782
  declare function otTagToLanguage(tag: string): string;
609
783
  //#endregion
610
- export { AxisInfo, Blob, Buffer, BufferContentType, BufferFlag, BufferSerializeFlag, BufferSerializeFormat, Direction, Face, FeatureNameIds, Font, FontExtents, FontFuncs, GlyphClass, GlyphExtents, GlyphFlag, GlyphInfo, GlyphPosition, HarfBuzzModule, JsonGlyph, NameEntry, SvgPathCommand, TraceEntry, TracePhase, otTagToLanguage, otTagToScript, shape, shapeWithTrace, version, versionString };
784
+ export { AxisInfo, Blob, Buffer, BufferContentType, BufferFlag, BufferSerializeFlag, BufferSerializeFormat, ClusterLevel, Direction, Face, Feature, FeatureNameIds, Font, FontExtents, FontFuncs, GlyphClass, GlyphExtents, GlyphFlag, GlyphInfo, GlyphPosition, HarfBuzzModule, NameEntry, SvgPathCommand, TraceEntry, TracePhase, Variation, otTagToLanguage, otTagToScript, shape, shapeWithTrace, version, versionString };