Add Direction class wrapping hb_direction_t

Author: khaledhosny

MIGRATING.md

@@ -71,6 +71,7 @@ Affected APIs:
 - `shape` and `shapeWithTrace` now take `Feature[]` instead of a comma-separated string. Use the new `Feature` class (e.g. `new Feature("liga", 0)` or `Feature.fromString("-liga")`).
 - `Buffer.setLanguage`, `Face.getName`, `Face.listNames`, and `otTagToLanguage` now use the new `Language` class instead of plain BCP 47 strings (e.g. `buffer.setLanguage(new Language("en"))`).
 - `Buffer.setScript` and `otTagToScript` now use the new `Script` class instead of plain ISO 15924 tag strings (e.g. `buffer.setScript(new Script("Latn"))` or, for the predefined ISO 15924 scripts, `buffer.setScript(Script.LATIN)`).
+- `Direction` is now a class with `INVALID`/`LTR`/`RTL`/`TTB`/`BTT` static instances and a string constructor. `Buffer.setDirection` takes a `Direction` instance; the call form `buffer.setDirection(Direction.RTL)` shown in the v0 → v1 table above keeps working.
 - `Buffer.addText` / `Buffer.addCodePoints`: `itemLength` accepts `undefined` (or omission), instead of `null`.
 - `Face.getFeatureNameIds`: returns `undefined` on failure, instead of `null`.
 - `Font.glyphHOrigin` / `glyphVOrigin` / `glyphExtents` / `glyphFromName`: return `undefined` on failure, instead of `null`.

harfbuzz.symbols

@@ -16,6 +16,8 @@ _hb_buffer_get_content_type
 _hb_buffer_guess_segment_properties
 _hb_buffer_set_cluster_level
 _hb_buffer_set_direction
+_hb_direction_from_string
+_hb_direction_to_string
 _hb_buffer_set_flags
 _hb_buffer_set_language
 _hb_buffer_set_script

src/buffer.ts

@@ -11,6 +11,7 @@ import type { GlyphInfo, GlyphPosition } from "./types";
 import { Font } from "./font";
 import type { Language } from "./language";
 import type { Script } from "./script";
+import type { Direction } from "./direction";
 
 export const BufferContentType = {
   INVALID: 0,
@@ -45,15 +46,6 @@ export const BufferFlag = {
 } as const;
 export type BufferFlag = ValueOf<typeof BufferFlag>;
 
-export const Direction = {
-  INVALID: 0,
-  LTR: 4,
-  RTL: 5,
-  TTB: 6,
-  BTT: 7,
-} as const;
-export type Direction = ValueOf<typeof Direction>;
-
 export const ClusterLevel = {
   MONOTONE_GRAPHEMES: 0,
   MONOTONE_CHARACTERS: 1,
@@ -162,10 +154,10 @@ export class Buffer {
 
   /**
    * Set buffer direction explicitly.
-   * @param dir A {@link Direction} value.
+   * @param dir The buffer direction.
    */
   setDirection(dir: Direction): void {
-    exports.hb_buffer_set_direction(this.ptr, dir);
+    exports.hb_buffer_set_direction(this.ptr, dir.value);
   }
 
   /**

src/direction.ts

@@ -0,0 +1,49 @@
+import { exports, string_to_ascii_ptr, utf8_ptr_to_string } from "./helpers";
+
+/**
+ * The direction of a text segment or buffer.
+ *
+ * A segment can also be tested for horizontal or vertical orientation
+ * (irrespective of specific direction).
+ */
+export class Direction {
+  /** Initial, unset direction. */
+  static readonly INVALID = new Direction(0);
+  /** Text is set horizontally from left to right. */
+  static readonly LTR = new Direction(4);
+  /** Text is set horizontally from right to left. */
+  static readonly RTL = new Direction(5);
+  /** Text is set vertically from top to bottom. */
+  static readonly TTB = new Direction(6);
+  /** Text is set vertically from bottom to top. */
+  static readonly BTT = new Direction(7);
+
+  readonly value: number;
+
+  /**
+   * Converts a string to a Direction. Matching is loose and case-insensitive;
+   * the first letter determines the direction (`l`/`L`: LTR, `r`/`R`: RTL,
+   * `t`/`T`: TTB, `b`/`B`: BTT). Other strings yield `Direction.INVALID`.
+   * @param name A string like `"ltr"`, `"rtl"`, `"ttb"`, or `"btt"`.
+   */
+  constructor(name: string);
+  /** @internal Wrap an existing hb_direction_t. */
+  constructor(existingValue: number);
+  constructor(arg: string | number) {
+    if (typeof arg === "number") {
+      this.value = arg;
+    } else {
+      const strPtr = string_to_ascii_ptr(arg);
+      this.value = exports.hb_direction_from_string(strPtr.ptr, -1);
+      strPtr.free();
+    }
+  }
+
+  /**
+   * Converts the Direction to a string.
+   * @returns A string like `"ltr"`, `"rtl"`, `"ttb"`, `"btt"`, or `"invalid"`.
+   */
+  toString(): string {
+    return utf8_ptr_to_string(exports.hb_direction_to_string(this.value));
+  }
+}

src/index.ts

@@ -10,6 +10,7 @@ export * from "./buffer";
 export * from "./feature";
 export * from "./language";
 export * from "./script";
+export * from "./direction";
 export * from "./shape";
 
 init(await createHarfBuzz());

test/index.test.js

@@ -1082,6 +1082,21 @@ describe("Buffer", function () {
   });
 });
 
+describe("Direction", function () {
+  it("toString returns the lowercase direction name", function () {
+    expect(hb.Direction.LTR.toString()).to.equal("ltr");
+    expect(hb.Direction.RTL.toString()).to.equal("rtl");
+    expect(hb.Direction.TTB.toString()).to.equal("ttb");
+    expect(hb.Direction.BTT.toString()).to.equal("btt");
+    expect(hb.Direction.INVALID.toString()).to.equal("invalid");
+  });
+
+  it("string constructor parses the direction name", function () {
+    expect(new hb.Direction("ltr")).to.deep.equal(hb.Direction.LTR);
+    expect(new hb.Direction("RTL")).to.deep.equal(hb.Direction.RTL);
+  });
+});
+
 describe("Script", function () {
   it("toString returns the ISO 15924 tag", function () {
     expect(hb.Script.LATIN.toString()).to.equal("Latn");