harfbuzzjs 0.10.3 → 1.0.0-beta.1

package/dist/index.d.mts

@@ -0,0 +1,610 @@
+//#region src/types.d.ts
+interface FontExtents {
+  ascender: number;
+  descender: number;
+  lineGap: number;
+}
+interface GlyphExtents {
+  xBearing: number;
+  yBearing: number;
+  width: number;
+  height: number;
+}
+interface GlyphInfo {
+  /** Either a Unicode code point (before shaping) or a glyph index (after shaping). */
+  codepoint: number;
+  /** The cluster index of the glyph. */
+  cluster: number;
+}
+interface GlyphPosition {
+  /** The x advance of the glyph. */
+  xAdvance: number;
+  /** The y advance of the glyph. */
+  yAdvance: number;
+  /** The x offset of the glyph. */
+  xOffset: number;
+  /** The y offset of the glyph. */
+  yOffset: number;
+}
+interface JsonGlyph {
+  /** The glyph ID. */
+  g: number;
+  /** The cluster ID. */
+  cl: number;
+  /** Advance width (width to advance after this glyph is painted). */
+  ax: number;
+  /** Advance height (height to advance after this glyph is painted). */
+  ay: number;
+  /** X displacement (adjustment in X dimension when painting this glyph). */
+  dx: number;
+  /** Y displacement (adjustment in Y dimension when painting this glyph). */
+  dy: number;
+  /** Glyph flags, a combination of {@link GlyphFlag} values. */
+  fl: number;
+}
+interface SvgPathCommand {
+  type: string;
+  values: number[];
+}
+interface AxisInfo {
+  min: number;
+  default: number;
+  max: number;
+}
+interface NameEntry {
+  nameId: number;
+  language: string;
+}
+interface FeatureNameIds {
+  uiLabelNameId: number | null;
+  uiTooltipTextNameId: number | null;
+  sampleTextNameId: number | null;
+  paramUiLabelNameIds: number[];
+}
+interface TraceEntry {
+  m: string;
+  t: unknown[];
+  glyphs: boolean;
+}
+/** EmscriptenModule extended with MODULARIZE runtime methods. */
+interface HarfBuzzModule extends EmscriptenModule {
+  wasmExports: Record<string, (...args: any[]) => any>;
+  addFunction(func: (...args: any[]) => any, signature: string): number;
+  removeFunction(funcPtr: number): void;
+  stackSave(): number;
+  stackAlloc(size: number): number;
+  stackRestore(ptr: number): void;
+}
+declare const GlyphFlag: {
+  readonly UNSAFE_TO_BREAK: 1;
+  readonly UNSAFE_TO_CONCAT: 2;
+  readonly SAFE_TO_INSERT_TATWEEL: 4;
+  readonly DEFINED: 7;
+};
+type GlyphFlag = (typeof GlyphFlag)[keyof typeof GlyphFlag];
+//#endregion
+//#region src/blob.d.ts
+/**
+ * An object representing a {@link https://harfbuzz.github.io/harfbuzz-hb-blob.html | HarfBuzz blob}.
+ * A blob wraps a chunk of binary data, typically the contents of a font file.
+ */
+declare class Blob {
+  readonly ptr: number;
+  /**
+   * @param data Binary font data.
+   */
+  constructor(data: ArrayBuffer);
+}
+//#endregion
+//#region src/face.d.ts
+declare const GlyphClass: {
+  readonly UNCLASSIFIED: 0;
+  readonly BASE_GLYPH: 1;
+  readonly LIGATURE: 2;
+  readonly MARK: 3;
+  readonly COMPONENT: 4;
+};
+type GlyphClass = (typeof GlyphClass)[keyof typeof GlyphClass];
+/**
+ * An object representing a {@link https://harfbuzz.github.io/harfbuzz-hb-face.html | HarfBuzz face}.
+ * A face represents a single face in a binary font file and is the
+ * foundation for creating Font objects used in text shaping.
+ */
+declare class Face {
+  readonly ptr: number;
+  readonly upem: number;
+  /**
+   * @param blob A Blob containing font data.
+   * @param index The index of the font in the blob. (0 for most files,
+   *  or a 0-indexed font number if the `blob` came from a font collection file.)
+   */
+  constructor(blob: Blob, index?: number);
+  /**
+   * Return the binary contents of an OpenType table.
+   * @param table Table name
+   * @returns A Uint8Array of the table data, or undefined if the table is not found.
+   */
+  referenceTable(table: string): Uint8Array | undefined;
+  /**
+   * Return variation axis infos.
+   * @returns A dictionary mapping axis tags to {min, default, max} values.
+   */
+  getAxisInfos(): Record<string, AxisInfo>;
+  /**
+   * Return unicodes the face supports.
+   * @returns A Uint32Array of supported Unicode code points.
+   */
+  collectUnicodes(): Uint32Array;
+  /**
+   * Return all scripts enumerated in the specified face's
+   * GSUB table or GPOS table.
+   * @param table The table to query, either "GSUB" or "GPOS".
+   * @returns An array of 4-character script tag strings.
+   */
+  getTableScriptTags(table: string): string[];
+  /**
+   * Return all features enumerated in the specified face's
+   * GSUB table or GPOS table.
+   * @param table The table to query, either "GSUB" or "GPOS".
+   * @returns An array of 4-character feature tag strings.
+   */
+  getTableFeatureTags(table: string): string[];
+  /**
+   * Return language tags in the given face's GSUB or GPOS table, underneath
+   * the specified script index.
+   * @param table The table to query, either "GSUB" or "GPOS".
+   * @param scriptIndex The index of the script to query.
+   * @returns An array of 4-character language tag strings.
+   */
+  getScriptLanguageTags(table: string, scriptIndex: number): string[];
+  /**
+   * Return all features in the specified face's GSUB table or GPOS table,
+   * underneath the specified script and language.
+   * @param table The table to query, either "GSUB" or "GPOS".
+   * @param scriptIndex The index of the script to query.
+   * @param languageIndex The index of the language to query.
+   * @returns An array of 4-character feature tag strings.
+   */
+  getLanguageFeatureTags(table: string, scriptIndex: number, languageIndex: number): string[];
+  /**
+   * Get the GDEF class of the requested glyph.
+   * @param glyph The glyph to get the class of.
+   * @returns The {@link GlyphClass} of the glyph.
+   */
+  getGlyphClass(glyph: number): GlyphClass;
+  /**
+   * Return all names in the specified face's name table.
+   * @returns An array of {nameId, language} entries.
+   */
+  listNames(): NameEntry[];
+  /**
+   * Get the name of the specified face.
+   * @param nameId The ID of the name to get.
+   * @param language The language of the name to get.
+   * @returns The name string.
+   */
+  getName(nameId: number, language: string): string;
+  /**
+   * Get the name IDs of the specified feature.
+   * @param table The table to query, either "GSUB" or "GPOS".
+   * @param featureIndex The index of the feature to query.
+   * @returns An object with name IDs, or null if not found.
+   */
+  getFeatureNameIds(table: string, featureIndex: number): FeatureNameIds | null;
+}
+//#endregion
+//#region src/font-funcs.d.ts
+/**
+ * An object representing {@link https://harfbuzz.github.io/harfbuzz-hb-font.html | HarfBuzz font functions}.
+ * Font functions define the methods used by a Font for lower-level queries
+ * like glyph advances and extents. HarfBuzz provides built-in default
+ * implementations which can be selectively overridden.
+ */
+declare class FontFuncs {
+  readonly ptr: number;
+  constructor();
+  /**
+   * Set the font's glyph extents function.
+   * @param func The callback receives a Font and glyph ID. It should return
+   * an object with xBearing, yBearing, width, and height, or null on failure.
+   */
+  setGlyphExtentsFunc(func: (font: Font, glyph: number) => GlyphExtents | null): void;
+  /**
+   * Set the font's glyph from name function.
+   * @param func The callback receives a Font and glyph name. It should return
+   * the glyph ID, or null on failure.
+   */
+  setGlyphFromNameFunc(func: (font: Font, name: string) => number | null): void;
+  /**
+   * Set the font's glyph horizontal advance function.
+   * @param func The callback receives a Font and glyph ID. It should return
+   * the horizontal advance of the glyph.
+   */
+  setGlyphHAdvanceFunc(func: (font: Font, glyph: number) => number): void;
+  /**
+   * Set the font's glyph vertical advance function.
+   * @param func The callback receives a Font and glyph ID. It should return
+   * the vertical advance of the glyph.
+   */
+  setGlyphVAdvanceFunc(func: (font: Font, glyph: number) => number): void;
+  /**
+   * Set the font's glyph horizontal origin function.
+   * @param func The callback receives a Font and glyph ID. It should return
+   * the [x, y] horizontal origin of the glyph, or null on failure.
+   */
+  setGlyphHOriginFunc(func: (font: Font, glyph: number) => [number, number] | null): void;
+  /**
+   * Set the font's glyph vertical origin function.
+   * @param func The callback receives a Font and glyph ID. It should return
+   * the [x, y] vertical origin of the glyph, or null on failure.
+   */
+  setGlyphVOriginFunc(func: (font: Font, glyph: number) => [number, number] | null): void;
+  /**
+   * Set the font's glyph horizontal kerning function.
+   * @param func The callback receives a Font, first glyph ID, and second glyph ID.
+   * It should return the horizontal kerning of the glyphs.
+   */
+  setGlyphHKerningFunc(func: (font: Font, firstGlyph: number, secondGlyph: number) => number): void;
+  /**
+   * Set the font's glyph name function.
+   * @param func The callback receives a Font and glyph ID. It should return
+   * the name of the glyph, or null on failure.
+   */
+  setGlyphNameFunc(func: (font: Font, glyph: number) => string | null): void;
+  /**
+   * Set the font's nominal glyph function.
+   * @param func The callback receives a Font and unicode code point. It should
+   * return the nominal glyph of the unicode, or null on failure.
+   */
+  setNominalGlyphFunc(func: (font: Font, unicode: number) => number | null): void;
+  /**
+   * Set the font's variation glyph function.
+   * @param func The callback receives a Font, unicode code point, and variation
+   * selector. It should return the variation glyph, or null on failure.
+   */
+  setVariationGlyphFunc(func: (font: Font, unicode: number, variationSelector: number) => number | null): void;
+  /**
+   * Set the font's horizontal extents function.
+   * @param func The callback receives a Font. It should return an object with
+   * ascender, descender, and lineGap, or null on failure.
+   */
+  setFontHExtentsFunc(func: (font: Font) => FontExtents | null): void;
+  /**
+   * Set the font's vertical extents function.
+   * @param func The callback receives a Font. It should return an object with
+   * ascender, descender, and lineGap, or null on failure.
+   */
+  setFontVExtentsFunc(func: (font: Font) => FontExtents | null): void;
+}
+//#endregion
+//#region src/font.d.ts
+/**
+ * An object representing a {@link https://harfbuzz.github.io/harfbuzz-hb-font.html | HarfBuzz font}.
+ * A font represents a face at a specific size and with certain other
+ * parameters (pixels-per-em, variation settings) specified. Fonts are the
+ * primary input to the shaping process.
+ */
+declare class Font {
+  readonly ptr: number;
+  private drawPtrs;
+  /**
+   * @param face A Face to create the font from.
+   */
+  constructor(face: Face);
+  /** @internal Wrap an existing font pointer. */
+  constructor(existingPtr: number);
+  /**
+   * Create a sub font that inherits this font's properties.
+   * @returns A new Font object representing the sub font.
+   */
+  subFont(): Font;
+  /**
+   * Return font horizontal extents.
+   * @returns Object with ascender, descender, and lineGap properties.
+   */
+  hExtents(): FontExtents;
+  /**
+   * Return font vertical extents.
+   * @returns Object with ascender, descender, and lineGap properties.
+   */
+  vExtents(): FontExtents;
+  /**
+   * Return glyph name.
+   * @param glyphId ID of the requested glyph in the font.
+   * @returns The glyph name string.
+   */
+  glyphName(glyphId: number): string;
+  /**
+   * Return a glyph as an SVG path string.
+   * @param glyphId ID of the requested glyph in the font.
+   * @returns SVG path data string.
+   */
+  glyphToPath(glyphId: number): string;
+  /**
+   * Return glyph horizontal advance.
+   * @param glyphId ID of the requested glyph in the font.
+   * @returns The horizontal advance width.
+   */
+  glyphHAdvance(glyphId: number): number;
+  /**
+   * Return glyph vertical advance.
+   * @param glyphId ID of the requested glyph in the font.
+   * @returns The vertical advance height.
+   */
+  glyphVAdvance(glyphId: number): number;
+  /**
+   * Return glyph horizontal origin.
+   * @param glyphId ID of the requested glyph in the font.
+   * @returns [x, y] origin coordinates, or null if not available.
+   */
+  glyphHOrigin(glyphId: number): [number, number] | null;
+  /**
+   * Return glyph vertical origin.
+   * @param glyphId ID of the requested glyph in the font.
+   * @returns [x, y] origin coordinates, or null if not available.
+   */
+  glyphVOrigin(glyphId: number): [number, number] | null;
+  /**
+   * Return glyph extents.
+   * @param glyphId ID of the requested glyph in the font.
+   * @returns An object with xBearing, yBearing, width, and height, or null.
+   */
+  glyphExtents(glyphId: number): GlyphExtents | null;
+  /**
+   * Return glyph ID from name.
+   * @param name Name of the requested glyph in the font.
+   * @returns The glyph ID, or null if not found.
+   */
+  glyphFromName(name: string): number | null;
+  /**
+   * Return a glyph as a JSON path string
+   * based on format described on https://svgwg.org/specs/paths/#InterfaceSVGPathSegment
+   * @param glyphId ID of the requested glyph in the font.
+   * @returns An array of path segment objects with type and values.
+   */
+  glyphToJson(glyphId: number): SvgPathCommand[];
+  /**
+   * Set the font's scale factor, affecting the position values returned from
+   * shaping.
+   * @param xScale Units to scale in the X dimension.
+   * @param yScale Units to scale in the Y dimension.
+   */
+  setScale(xScale: number, yScale: number): void;
+  /**
+   * Set the font's variations.
+   * @param variations Dictionary of variations to set.
+   */
+  setVariations(variations: Record<string, number>): void;
+  /** Set the font's font functions. */
+  setFuncs(fontFuncs: FontFuncs): void;
+}
+//#endregion
+//#region src/buffer.d.ts
+declare const BufferContentType: {
+  readonly INVALID: 0;
+  readonly UNICODE: 1;
+  readonly GLYPHS: 2;
+};
+type BufferContentType = (typeof BufferContentType)[keyof typeof BufferContentType];
+declare const BufferSerializeFlag: {
+  readonly DEFAULT: 0;
+  readonly NO_CLUSTERS: 1;
+  readonly NO_POSITIONS: 2;
+  readonly NO_GLYPH_NAMES: 4;
+  readonly GLYPH_EXTENTS: 8;
+  readonly GLYPH_FLAGS: 16;
+  readonly NO_ADVANCES: 32;
+  readonly DEFINED: 63;
+};
+type BufferSerializeFlag = (typeof BufferSerializeFlag)[keyof typeof BufferSerializeFlag];
+declare const BufferFlag: {
+  readonly DEFAULT: 0;
+  readonly BOT: 1;
+  readonly EOT: 2;
+  readonly PRESERVE_DEFAULT_IGNORABLES: 4;
+  readonly REMOVE_DEFAULT_IGNORABLES: 8;
+  readonly DO_NOT_INSERT_DOTTED_CIRCLE: 16;
+  readonly VERIFY: 32;
+  readonly PRODUCE_UNSAFE_TO_CONCAT: 64;
+  readonly PRODUCE_SAFE_TO_INSERT_TATWEEL: 128;
+  readonly DEFINED: 255;
+};
+type BufferFlag = (typeof BufferFlag)[keyof typeof BufferFlag];
+declare const Direction: {
+  readonly INVALID: 0;
+  readonly LTR: 4;
+  readonly RTL: 5;
+  readonly TTB: 6;
+  readonly BTT: 7;
+};
+type Direction = (typeof Direction)[keyof typeof Direction];
+declare const BufferSerializeFormat: {
+  readonly INVALID: 0;
+  readonly TEXT: number;
+  readonly JSON: number;
+};
+type BufferSerializeFormat = (typeof BufferSerializeFormat)[keyof typeof BufferSerializeFormat];
+/**
+ * An object representing a {@link https://harfbuzz.github.io/harfbuzz-hb-buffer.html | HarfBuzz buffer}.
+ * A buffer holds the input text and its properties before shaping, and the
+ * output glyphs and their information after shaping.
+ */
+declare class Buffer {
+  readonly ptr: number;
+  constructor();
+  /** @internal Wrap an existing buffer pointer. */
+  constructor(existingPtr: number);
+  /**
+   * Add text to the buffer.
+   * @param text Text to be added to the buffer.
+   * @param itemOffset The offset of the first character to add to the buffer.
+   * @param itemLength The number of characters to add to the buffer, or null for the end of text.
+   */
+  addText(text: string, itemOffset?: number, itemLength?: number | null): void;
+  /**
+   * Add code points to the buffer.
+   * @param codePoints Array of code points to be added to the buffer.
+   * @param itemOffset The offset of the first code point to add to the buffer.
+   * @param itemLength The number of code points to add to the buffer, or null for the end of the array.
+   */
+  addCodePoints(codePoints: number[], itemOffset?: number, itemLength?: number | null): void;
+  /**
+   * Set buffer script, language and direction.
+   *
+   * This needs to be done before shaping.
+   */
+  guessSegmentProperties(): void;
+  /**
+   * Set buffer direction explicitly.
+   * @param dir A {@link Direction} value.
+   */
+  setDirection(dir: Direction): void;
+  /**
+   * Set buffer flags explicitly.
+   * @param flags A combination of {@link BufferFlag} values (OR them together).
+   */
+  setFlags(flags: number): void;
+  /**
+   * Set buffer language explicitly.
+   * @param language The buffer language
+   */
+  setLanguage(language: string): void;
+  /**
+   * Set buffer script explicitly.
+   * @param script The buffer script
+   */
+  setScript(script: string): void;
+  /**
+   * Set the HarfBuzz clustering level.
+   *
+   * Affects the cluster values returned from shaping.
+   * @param level Clustering level. See the HarfBuzz manual chapter on Clusters.
+   */
+  setClusterLevel(level: number): void;
+  /** Reset the buffer to its initial status. */
+  reset(): void;
+  /**
+   * Similar to reset(), but does not clear the Unicode functions and the
+   * replacement code point.
+   */
+  clearContents(): void;
+  /**
+   * Set message func.
+   * @param func The function to set. It receives the buffer, font, and message
+   * string as arguments. Returning false will skip this shaping step and move
+   * to the next one.
+   */
+  setMessageFunc(func: (buffer: Buffer, font: Font, message: string) => boolean): void;
+  /**
+   * Get the the number of items in the buffer.
+   * @returns The buffer length.
+   */
+  getLength(): number;
+  /**
+   * Get the glyph information from the buffer.
+   * @returns An array of {@link GlyphInfo} objects.
+   */
+  getGlyphInfos(): GlyphInfo[];
+  /**
+   * Get the glyph positions from the buffer.
+   * @returns An array of {@link GlyphPosition} objects.
+   */
+  getGlyphPositions(): GlyphPosition[];
+  /**
+   * Get the glyph information and positions from the buffer.
+   * @returns The glyph information and positions.
+   *
+   * The glyph information is returned as an array of objects with the
+   * properties from getGlyphInfos and getGlyphPositions combined.
+   */
+  getGlyphInfosAndPositions(): (GlyphInfo & Partial<GlyphPosition>)[];
+  /**
+   * Update the glyph positions in the buffer.
+   * WARNING: Do not use unless you know what you are doing.
+   */
+  updateGlyphPositions(positions: GlyphPosition[]): void;
+  /**
+   * Serialize the buffer contents to a string.
+   * @param font The font to use for serialization.
+   * @param start The starting index of the glyphs to serialize.
+   * @param end The ending index of the glyphs to serialize.
+   * @param format The {@link BufferSerializeFormat} to serialize the buffer contents to.
+   * @param flags A combination of {@link BufferSerializeFlag} values (OR them together).
+   *
+   * @returns The serialized buffer contents.
+   */
+  serialize(font?: Font | null, start?: number, end?: number | null, format?: BufferSerializeFormat, flags?: number): string;
+  /**
+   * Return the buffer content type.
+   *
+   * @returns The buffer content type as a {@link BufferContentType} value.
+   */
+  getContentType(): BufferContentType;
+  /**
+   * Return the buffer contents as a JSON object.
+   * @returns An array of {@link JsonGlyph} objects.
+   */
+  json(): JsonGlyph[];
+}
+//#endregion
+//#region src/shape.d.ts
+declare const TracePhase: {
+  readonly DONT_STOP: 0;
+  readonly GSUB: 1;
+  readonly GPOS: 2;
+};
+type TracePhase = (typeof TracePhase)[keyof typeof TracePhase];
+/**
+ * Shape a buffer with a given font.
+ *
+ * Converts the Unicode text in the buffer into positioned glyphs.
+ * The buffer is modified in place.
+ *
+ * @param font The Font to shape with.
+ * @param buffer The Buffer containing text to shape, suitably prepared
+ *   (text added, segment properties set).
+ * @param features A string of comma-separated OpenType features to apply.
+ */
+declare function shape(font: Font, buffer: Buffer, features?: string): void;
+/**
+ * Shape a buffer with a given font, returning a JSON trace of the shaping process.
+ *
+ * This function supports "partial shaping", where the shaping process is
+ * terminated after a given lookup ID is reached.
+ *
+ * @param font The Font to shape with.
+ * @param buffer The Buffer containing text to shape, suitably prepared.
+ * @param features A string of comma-separated OpenType features to apply.
+ * @param stop_at A lookup ID at which to terminate shaping.
+ * @param stop_phase The {@link TracePhase} at which to stop shaping.
+ * @returns An array of trace entries, each with a message, serialized glyphs, and phase info.
+ */
+declare function shapeWithTrace(font: Font, buffer: Buffer, features: string, stop_at: number, stop_phase: TracePhase): TraceEntry[];
+/**
+ * Return the HarfBuzz version.
+ * @returns An object with major, minor, and micro version numbers.
+ */
+declare function version(): {
+  major: number;
+  minor: number;
+  micro: number;
+};
+/**
+ * Return the HarfBuzz version as a string.
+ * @returns A version string in the form "major.minor.micro".
+ */
+declare function versionString(): string;
+/**
+ * Convert an OpenType script tag to HarfBuzz script.
+ * @param tag The tag to convert.
+ * @returns The script.
+ */
+declare function otTagToScript(tag: string): string;
+/**
+ * Convert an OpenType language tag to HarfBuzz language.
+ * @param tag The tag to convert.
+ * @returns The language.
+ */
+declare function otTagToLanguage(tag: string): string;
+//#endregion
+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 };