@mathlabs/tikra 1.1.1 → 1.2.0

package/README.md

@@ -30,7 +30,7 @@ import { writeFileSync } from "node:fs";
 const svg = tikzToSvg(String.raw`\begin{tikzpicture}\draw[->] (0,0) -- (2,1) node[right] {$\vec v$};\end{tikzpicture}`);
 writeFileSync("v.svg", svg);
 writeFileSync("v.png", png(svg, { dpi: 300 }));
-const { warnings } = render(String.raw`\tikz \draw (0,0) circle (1);`);   // []
+const { warnings, alt } = render(String.raw`\tikz \draw (0,0) circle (1);`);   // [], "Drawing of one shape, without text"
 ```
 
 ## Browsers and bundlers (Vite, webpack, esbuild)
@@ -59,8 +59,8 @@ Without a bundler, from a CDN:
 | | |
 |---|---|
 | `init(input?)` | Loads the wasm. Needed once in browsers and bundlers; does nothing in Node. `input` overrides where the wasm comes from (a URL, a `Response`, bytes or a `WebAssembly.Module`). |
-| `tikzToSvg(code)` | The SVG as a string. |
-| `render(code)` | `{ svg, warnings }`: `warnings` lists, as strings, what was ignored or approximated. |
+| `tikzToSvg(code, options?)` | The SVG as a string. `options.locale` (`"en"` by default, or `"pt-BR"`, `"es"`, `"fr"`, `"de"`, `"it"`, `"ru"`, `"zh"`, `"ja"`, `"ko"`, `"hi"`, `"ar"`, `"id"`, `"tr"`, `"nl"`, `"pl"`) is the language of the figure in words; the drawing is the same in all. |
+| `render(code, options?)` | `{ svg, alt, description, warnings }`, the words in `options.locale`: `alt` is the figure in one sentence (the SVG's `<title>`, for an image's `alt`), `description` the figure in words (the SVG's `<desc>`: a chart's axes and data, a diagram's nodes and connections), and `warnings` lists, as strings, what was ignored or approximated. When the picture has its author's text (`\begin{tikzpicture}[alt={…}]`), `alt` and `description` are that text. The words tikra writes are not perfect (they say what is in the drawing, not what it means, and little about free drawings): review them before publishing. |
 | `png(svg, options?)` | PNG bytes as a `Uint8Array`. Options: `dpi` (300 by default) and `background` (`true`, white, by default; `false` for transparent). |
 | `version()` | The version of tikra's core inside the package (the npm package has its own version). |
 

package/index.d.cts

@@ -1,10 +1,22 @@
 export interface Result {
   /** Standalone SVG, with math labels typeset by mathra. */
   svg: string;
+  /** The figure in a sentence, for readers who cannot see it: the SVG's `<title>`, an image's `alt`. */
+  alt: string;
+  /** The figure in words (axes, data, nodes and their connections): the SVG's `<desc>`. */
+  description: string;
   /** What was ignored or approximated: unsupported commands, labels with broken LaTeX. */
   warnings: string[];
 }
 
+/** mathra's languages: the figure in words (`alt`, `description`) is told in them; the drawing is the same. */
+export type Locale = "en" | "pt-BR" | "es" | "fr" | "de" | "it" | "ru" | "zh" | "ja" | "ko" | "hi" | "ar" | "id" | "tr" | "nl" | "pl";
+
+export interface Options {
+  /** The language of the figure in words. Default `"en"`. A code with a region (`"es-MX"`) takes its language. */
+  locale?: Locale | (string & {});
+}
+
 export interface PngOptions {
   /** Resolution. Default 300, for print. */
   dpi?: number;
@@ -15,11 +27,11 @@ export interface PngOptions {
 /** Loads the WebAssembly module: await it once before converting in browsers and bundlers. In Node it does nothing. */
 export function init(input?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module): Promise<void>;
 
-/** Converts a TikZ figure (a `standalone` document, a `tikzpicture`, `\tikz`, an `axis` or loose statements) to SVG. Throws when there is no figure to draw. */
-export function tikzToSvg(code: string): string;
+/** Converts a TikZ figure (a `standalone` document, a `tikzpicture`, `\tikz`, an `axis` or loose statements) to SVG, with the figure in words in `options.locale`. Throws when there is no figure to draw or the locale is unknown. */
+export function tikzToSvg(code: string, options?: Options): string;
 
-/** Converts a TikZ figure and returns the SVG with the warnings. */
-export function render(code: string): Result;
+/** Converts a TikZ figure and returns the SVG, the figure in words and the warnings. */
+export function render(code: string, options?: Options): Result;
 
 /** Rasterizes an SVG written by tikra to PNG bytes. Throws on an invalid SVG or dpi, or past 100 megapixels. */
 export function png(svg: string, options?: PngOptions): Uint8Array;

package/index.d.ts

@@ -1,10 +1,22 @@
 export interface Result {
   /** Standalone SVG, with math labels typeset by mathra. */
   svg: string;
+  /** The figure in a sentence, for readers who cannot see it: the SVG's `<title>`, an image's `alt`. */
+  alt: string;
+  /** The figure in words (axes, data, nodes and their connections): the SVG's `<desc>`. */
+  description: string;
   /** What was ignored or approximated: unsupported commands, labels with broken LaTeX. */
   warnings: string[];
 }
 
+/** mathra's languages: the figure in words (`alt`, `description`) is told in them; the drawing is the same. */
+export type Locale = "en" | "pt-BR" | "es" | "fr" | "de" | "it" | "ru" | "zh" | "ja" | "ko" | "hi" | "ar" | "id" | "tr" | "nl" | "pl";
+
+export interface Options {
+  /** The language of the figure in words. Default `"en"`. A code with a region (`"es-MX"`) takes its language. */
+  locale?: Locale | (string & {});
+}
+
 export interface PngOptions {
   /** Resolution. Default 300, for print. */
   dpi?: number;
@@ -15,11 +27,11 @@ export interface PngOptions {
 /** Loads the WebAssembly module: await it once before converting in browsers and bundlers. In Node it does nothing. */
 export function init(input?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module): Promise<void>;
 
-/** Converts a TikZ figure (a `standalone` document, a `tikzpicture`, `\tikz`, an `axis` or loose statements) to SVG. Throws when there is no figure to draw. */
-export function tikzToSvg(code: string): string;
+/** Converts a TikZ figure (a `standalone` document, a `tikzpicture`, `\tikz`, an `axis` or loose statements) to SVG, with the figure in words in `options.locale`. Throws when there is no figure to draw or the locale is unknown. */
+export function tikzToSvg(code: string, options?: Options): string;
 
-/** Converts a TikZ figure and returns the SVG with the warnings. */
-export function render(code: string): Result;
+/** Converts a TikZ figure and returns the SVG, the figure in words and the warnings. */
+export function render(code: string, options?: Options): Result;
 
 /** Rasterizes an SVG written by tikra to PNG bytes. Throws on an invalid SVG or dpi, or past 100 megapixels. */
 export function png(svg: string, options?: PngOptions): Uint8Array;

package/node/tikra_wasm.cjs

@@ -19,28 +19,31 @@ function png(svg, dpi, background) {
 exports.png = png;
 
 /**
- * The SVG and what was ignored or approximated, as JSON (see `convert_json`).
+ * The SVG, the figure in words and what was ignored or approximated, as JSON (see `convert_json`).
  * @param {string} code
+ * @param {string | null} [locale]
  * @returns {string}
  */
-function render(code) {
-    let deferred3_0;
-    let deferred3_1;
+function render(code, locale) {
+    let deferred4_0;
+    let deferred4_1;
     try {
         const ptr0 = passStringToWasm0(code, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.render(ptr0, len0);
-        var ptr2 = ret[0];
-        var len2 = ret[1];
+        var ptr1 = isLikeNone(locale) ? 0 : passStringToWasm0(locale, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len1 = WASM_VECTOR_LEN;
+        const ret = wasm.render(ptr0, len0, ptr1, len1);
+        var ptr3 = ret[0];
+        var len3 = ret[1];
         if (ret[3]) {
-            ptr2 = 0; len2 = 0;
+            ptr3 = 0; len3 = 0;
             throw takeFromExternrefTable0(ret[2]);
         }
-        deferred3_0 = ptr2;
-        deferred3_1 = len2;
-        return getStringFromWasm0(ptr2, len2);
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
     } finally {
-        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
     }
 }
 exports.render = render;
@@ -48,26 +51,29 @@ exports.render = render;
 /**
  * Converts a TikZ figure (a `standalone` document, a `tikzpicture`, `\tikz` or an `axis`) to SVG.
  * @param {string} code
+ * @param {string | null} [locale]
  * @returns {string}
  */
-function tikzToSvg(code) {
-    let deferred3_0;
-    let deferred3_1;
+function tikzToSvg(code, locale) {
+    let deferred4_0;
+    let deferred4_1;
     try {
         const ptr0 = passStringToWasm0(code, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.tikzToSvg(ptr0, len0);
-        var ptr2 = ret[0];
-        var len2 = ret[1];
+        var ptr1 = isLikeNone(locale) ? 0 : passStringToWasm0(locale, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len1 = WASM_VECTOR_LEN;
+        const ret = wasm.tikzToSvg(ptr0, len0, ptr1, len1);
+        var ptr3 = ret[0];
+        var len3 = ret[1];
         if (ret[3]) {
-            ptr2 = 0; len2 = 0;
+            ptr3 = 0; len3 = 0;
             throw takeFromExternrefTable0(ret[2]);
         }
-        deferred3_0 = ptr2;
-        deferred3_1 = len2;
-        return getStringFromWasm0(ptr2, len2);
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
     } finally {
-        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
     }
 }
 exports.tikzToSvg = tikzToSvg;

package/node/wrap.cjs

@@ -5,13 +5,13 @@ function wrap(raw, isReady) {
     if (!isReady()) throw new Error("tikra: call `await init()` once before converting (only needed outside Node)");
   };
   return {
-    tikzToSvg(code) {
+    tikzToSvg(code, options) {
       check();
-      return raw.tikzToSvg(code);
+      return raw.tikzToSvg(code, options?.locale ?? null);
     },
-    render(code) {
+    render(code, options) {
       check();
-      return JSON.parse(raw.render(code));
+      return JSON.parse(raw.render(code, options?.locale ?? null));
     },
     png(svg, options) {
       check();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mathlabs/tikra",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "TikZ and pgfplots figures to SVG and PNG, without a TeX install. Math labels typeset by mathra. Runs on WebAssembly in Node, bundlers and browsers.",
   "keywords": [
     "tikz",

package/web/tikra_wasm.js

@@ -18,54 +18,60 @@ export function png(svg, dpi, background) {
 }
 
 /**
- * The SVG and what was ignored or approximated, as JSON (see `convert_json`).
+ * The SVG, the figure in words and what was ignored or approximated, as JSON (see `convert_json`).
  * @param {string} code
+ * @param {string | null} [locale]
  * @returns {string}
  */
-export function render(code) {
-    let deferred3_0;
-    let deferred3_1;
+export function render(code, locale) {
+    let deferred4_0;
+    let deferred4_1;
     try {
         const ptr0 = passStringToWasm0(code, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.render(ptr0, len0);
-        var ptr2 = ret[0];
-        var len2 = ret[1];
+        var ptr1 = isLikeNone(locale) ? 0 : passStringToWasm0(locale, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len1 = WASM_VECTOR_LEN;
+        const ret = wasm.render(ptr0, len0, ptr1, len1);
+        var ptr3 = ret[0];
+        var len3 = ret[1];
         if (ret[3]) {
-            ptr2 = 0; len2 = 0;
+            ptr3 = 0; len3 = 0;
             throw takeFromExternrefTable0(ret[2]);
         }
-        deferred3_0 = ptr2;
-        deferred3_1 = len2;
-        return getStringFromWasm0(ptr2, len2);
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
     } finally {
-        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
     }
 }
 
 /**
  * Converts a TikZ figure (a `standalone` document, a `tikzpicture`, `\tikz` or an `axis`) to SVG.
  * @param {string} code
+ * @param {string | null} [locale]
  * @returns {string}
  */
-export function tikzToSvg(code) {
-    let deferred3_0;
-    let deferred3_1;
+export function tikzToSvg(code, locale) {
+    let deferred4_0;
+    let deferred4_1;
     try {
         const ptr0 = passStringToWasm0(code, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.tikzToSvg(ptr0, len0);
-        var ptr2 = ret[0];
-        var len2 = ret[1];
+        var ptr1 = isLikeNone(locale) ? 0 : passStringToWasm0(locale, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len1 = WASM_VECTOR_LEN;
+        const ret = wasm.tikzToSvg(ptr0, len0, ptr1, len1);
+        var ptr3 = ret[0];
+        var len3 = ret[1];
         if (ret[3]) {
-            ptr2 = 0; len2 = 0;
+            ptr3 = 0; len3 = 0;
             throw takeFromExternrefTable0(ret[2]);
         }
-        deferred3_0 = ptr2;
-        deferred3_1 = len2;
-        return getStringFromWasm0(ptr2, len2);
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
     } finally {
-        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
     }
 }
 

package/web/wrap.js

@@ -5,13 +5,13 @@ export function wrap(raw, isReady) {
     if (!isReady()) throw new Error("tikra: call `await init()` once before converting (only needed outside Node)");
   };
   return {
-    tikzToSvg(code) {
+    tikzToSvg(code, options) {
       check();
-      return raw.tikzToSvg(code);
+      return raw.tikzToSvg(code, options?.locale ?? null);
     },
-    render(code) {
+    render(code, options) {
       check();
-      return JSON.parse(raw.render(code));
+      return JSON.parse(raw.render(code, options?.locale ?? null));
     },
     png(svg, options) {
       check();