@spidunno/desmos-types 1.13.0 → 1.13.1

package/README.md

@@ -3,6 +3,17 @@
 TypeScript type definitions for the [Desmos API v1.13](https://www.desmos.com/api/v1.13/docs/index.html):
 the graphing calculator, geometry tool, 3D calculator, and the four-function and scientific calculators.
 
+## Install
+
+```sh
+npm install --save-dev @spidunno/desmos-types@~1.13.0
+```
+
+The package's major and minor version match the Desmos API version it describes; patch releases
+are fixes to the types. Use a tilde range (`~1.13.0`), not npm's default caret (`^`). A caret range
+would also accept a future `1.14.x`, which describes a different API version than the
+`calculator.js` you load.
+
 ## Usage
 
 Load the API as usual:
@@ -74,9 +85,12 @@ The types follow the official v1.13 documentation and were checked against the
 
 Members marked `@remarks Undocumented` exist in the bundle but not in the docs. Examples are the
 3D camera methods (`getOrientation`, `setOrientation`, `animateToOrientation`,
-`setPerspectiveDistortion`), `LabelSizes`, the extra `LabelOrientations`, `Abraham` and `MathQuill`.
+`setPerspectiveDistortion`), `LabelSizes`, the extra `LabelOrientations`, and `MathQuill`.
 They work in v1.13 but Desmos makes no promises about them.
 
+`Abraham` follows its own [documentation page](https://www.desmos.com/api/v1.13/docs/abraham.html).
+Desmos asks that you contact partnerships@desmos.com before using it.
+
 Internal exports are not part of the public types. `Desmos.Private` and the calculators' internal
 members are typed separately (see [Internals](#internals)). `Desmos.TestInternal`, `Desmos.config` and
 `Desmos.$` aren't typed at all.

package/internals/private.d.ts

@@ -12,8 +12,10 @@ declare namespace Desmos.Internals {
   } & FragileViews &
     FragileHelpers;
 
-  type Private = Omit<Generated.Private, 'Fragile'> & {
+  type Private = Omit<Generated.Private, 'Fragile' | 'Abraham'> & {
     Fragile: PrivateFragile;
+    /** The same object as {@link Desmos.Abraham}. */
+    Abraham: Desmos.Abraham;
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spidunno/desmos-types",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "TypeScript type definitions for the Desmos API v1.13",
   "types": "index.d.ts",
   "publishConfig": {
@@ -33,7 +33,6 @@
   "devDependencies": {
     "acorn": "^8.14.0",
     "acorn-walk": "^8.3.4",
-    "jsdom": "^24.1.3",
-    "typescript": "5.6.3"
+    "jsdom": "^24.1.3"
   }
 }

package/types/abraham.d.ts

@@ -2,54 +2,145 @@
  * Abraham: Desmos's library for translating between LaTeX and the Nemeth and
  * UEB Braille math codes, bundled into `calculator.js`.
  *
- * @remarks Undocumented: the docs only mention that the library exists. The
- * shapes below come from inspecting the v1.13 bundle and may change.
+ * Documented at https://www.desmos.com/api/v1.13/docs/abraham.html. Desmos
+ * asks that you contact partnerships@desmos.com before using it.
  */
 declare namespace Desmos {
+  /** A position in the translator's input. */
+  interface AbrahamLocation {
+    first_line: number;
+    last_line: number;
+    first_column: number;
+    last_column: number;
+  }
+
+  /** A place where permissive Braille→LaTeX translation inserted a missing delimiter. */
+  interface AbrahamWarning {
+    location: AbrahamLocation;
+  }
+
+  /** A successful LaTeX→Braille translation. */
+  interface AbrahamBrailleSuccess {
+    isError: false;
+    /** Six-dot Unicode Braille. */
+    value: string;
+  }
+
+  /** A successful Braille→LaTeX translation. */
+  interface AbrahamLatexSuccess {
+    isError: false;
+    value: Latex;
+    /** Where missing delimiters were inserted. Always empty with `strict: true`. */
+    warnings: AbrahamWarning[];
+  }
+
+  /** A successful translation in either direction. */
   interface AbrahamSuccess {
     isError: false;
     value: string;
     /** Present on Braille→LaTeX results. */
-    warnings?: unknown[];
+    warnings?: AbrahamWarning[];
   }
 
+  /** A failed translation (a parse error). */
   interface AbrahamFailure {
     isError: true;
     error: {
-      location?: {
-        first_line: number;
-        last_line: number;
-        first_column: number;
-        last_column: number;
-      };
-      [key: string]: unknown;
+      /** Where the parse error occurred. */
+      location: AbrahamLocation;
+      /** Developer diagnostics. Not part of the public API; its contents may change. */
+      _diagnostic?: unknown;
     };
   }
 
+  /** The result of `latexToNemeth` / `latexToUeb`. */
+  type AbrahamBrailleResult = AbrahamBrailleSuccess | AbrahamFailure;
+
+  /** The result of `nemethToLatex` / `uebToLatex`. */
+  type AbrahamLatexResult = AbrahamLatexSuccess | AbrahamFailure;
+
+  /** The result of any translation. */
   type AbrahamResult = AbrahamSuccess | AbrahamFailure;
 
+  interface AbrahamLatexToBrailleOptions {
+    /**
+     * Operator names to recognize. Neither Braille code has a convention for
+     * `\operatorname`, so these are written as plain letters.
+     * @defaultValue Desmos's built-in list (`floor`, `mean`, `normaldist`, ...)
+     */
+    operatorNames?: readonly string[];
+  }
+
+  interface AbrahamBrailleToLatexOptions {
+    /**
+     * Treat missing delimiters (e.g. an unclosed fraction or radical) as parse
+     * errors instead of inserting them and reporting `warnings`.
+     * @defaultValue `false`
+     */
+    strict?: boolean;
+    /**
+     * Operator names to recognize in the Braille input, e.g. `['blah']` turns
+     * `blah(abc)` into `\operatorname{blah}(abc)`.
+     * @defaultValue Desmos's built-in list (`floor`, `mean`, `normaldist`, ...)
+     */
+    operatorNames?: readonly string[];
+  }
+
   interface Abraham {
     /** Library version, e.g. `'1.0.3'`. */
     readonly version: string;
-    /** LaTeX → Nemeth Braille (Unicode Braille cells). */
-    latexToNemeth(latex: Latex): AbrahamResult;
-    /** LaTeX → UEB Braille (Unicode Braille cells). */
-    latexToUeb(latex: Latex): AbrahamResult;
-    /** Nemeth Braille → LaTeX. */
-    nemethToLatex(braille: string): AbrahamResult;
-    /** UEB Braille → LaTeX. */
-    uebToLatex(braille: string): AbrahamResult;
+
+    /**
+     * LaTeX → Nemeth Braille.
+     * @example Abraham.latexToNemeth('e_{f}^{x^{2}}') // { isError: false, value: '⠑⠰⠋⠘⠭⠘⠘⠆' }
+     */
+    latexToNemeth(latex: Latex, options?: AbrahamLatexToBrailleOptions): AbrahamBrailleResult;
+
+    /**
+     * LaTeX → UEB Braille.
+     * @example Abraham.latexToUeb('1+1') // { isError: false, value: '⠼⠁⠐⠖⠼⠁' }
+     */
+    latexToUeb(latex: Latex, options?: AbrahamLatexToBrailleOptions): AbrahamBrailleResult;
+
+    /**
+     * Nemeth Braille → LaTeX. `braille` must be six-dot Unicode Braille; use
+     * `UnicodeBraille.coerceToSixDotCells` to convert other formats first.
+     * Unless `strict` is set, missing delimiters are inserted and reported in `warnings`.
+     * @example Abraham.nemethToLatex('⠹⠂⠌⠆') // value '\\frac{1}{2}', with one warning
+     */
+    nemethToLatex(braille: string, options?: AbrahamBrailleToLatexOptions): AbrahamLatexResult;
+
+    /**
+     * UEB Braille → LaTeX. `braille` must be six-dot Unicode Braille; use
+     * `UnicodeBraille.coerceToSixDotCells` to convert other formats first.
+     * Unless `strict` is set, missing delimiters are inserted and reported in `warnings`.
+     * @example Abraham.uebToLatex('⠼⠁⠐⠖⠼⠁') // { isError: false, value: '1+1', warnings: [] }
+     */
+    uebToLatex(braille: string, options?: AbrahamBrailleToLatexOptions): AbrahamLatexResult;
+
     /** Conversions between Unicode Braille and Braille ASCII. */
     readonly UnicodeBraille: {
-      /** Unicode Braille → Braille ASCII, e.g. `'⠭⠘⠆'` → `'X^2'`. */
+      /**
+       * Unicode Braille → Braille ASCII (upper case letters as a comma + letter digraph).
+       * @example toBrailleAscii('⠼⠁⠐⠖⠼⠁') // '#A"6#A'
+       */
       toBrailleAscii(braille: string): string;
-      /** Unicode Braille → expanded (lowercase) Braille ASCII, e.g. `'⠭⠘⠆'` → `'x~2'`. */
+      /**
+       * Unicode Braille → Expanded Braille ASCII, the eight-dot encoding common
+       * on refreshable displays.
+       * @example toExpandedBrailleAscii('⠼⠁⠐⠖⠼⠁') // '#a"6#a'
+       */
       toExpandedBrailleAscii(braille: string): string;
-      /** Reduce eight-dot cells to six-dot cells. */
-      coerceToSixDotCells(braille: string): string;
+      /**
+       * Coerce input to the six-dot Unicode Braille the translators expect:
+       * converts Braille ASCII or Expanded Braille ASCII (ignoring case), and
+       * strips the bottom pair of dots from eight-dot Unicode cells.
+       * @example coerceToSixDotCells('#A"6#A') // '⠼⠁⠐⠖⠼⠁'
+       */
+      coerceToSixDotCells(input: string): string;
     };
   }
 
-  /** @remarks Undocumented: may change without notice. */
+  /** The Abraham Braille translation library. */
   const Abraham: Abraham;
 }