@iyulab/declart-web 0.21.0 → 0.22.0

package/index.d.ts

@@ -1,32 +1,44 @@
+/** Options for the render functions. */
+export interface RenderOptions {
+  /**
+   * Leave the backdrop unpainted so the page shows through. Colors are unchanged —
+   * on a dark page use the `dark` theme so text stays legible.
+   */
+  transparent?: boolean;
+}
+
 /**
  * Renders a TOML or JSON diagram declaration to SVG.
  * @param input - TOML or JSON declaration string (format auto-detected)
- * @param theme - Theme name: 'default', 'monochrome', 'accessible', 'warm' (defaults to 'default')
+ * @param theme - Theme name: 'default', 'monochrome', 'accessible', 'warm', 'dark' (defaults to 'default')
  * @param width - Optional canvas width in pixels (height scales proportionally)
+ * @param options - `transparent: true` leaves the backdrop unpainted
  * @returns SVG string
  * @throws If the declaration is invalid
  */
-export function render(input: string, theme?: string, width?: number): string;
+export function render(input: string, theme?: string, width?: number, options?: RenderOptions): string;
 
 /**
  * Renders a JSON diagram declaration to SVG.
  * @param input - JSON declaration string
  * @param theme - Theme name (defaults to 'default')
  * @param width - Optional canvas width in pixels
+ * @param options - `transparent: true` leaves the backdrop unpainted
  * @returns SVG string
  * @throws If the JSON declaration is invalid
  */
-export function renderJson(input: string, theme?: string, width?: number): string;
+export function renderJson(input: string, theme?: string, width?: number, options?: RenderOptions): string;
 
 /**
  * Renders a TOML or JSON diagram declaration with a custom theme TOML.
  * @param input - TOML or JSON declaration string
  * @param themeToml - TOML theme definition string
  * @param width - Optional canvas width in pixels
+ * @param options - `transparent: true` leaves the backdrop unpainted
  * @returns SVG string
  * @throws If the declaration or theme is invalid
  */
-export function renderWithThemeToml(input: string, themeToml: string, width?: number): string;
+export function renderWithThemeToml(input: string, themeToml: string, width?: number, options?: RenderOptions): string;
 
 /**
  * Validates a TOML or JSON diagram declaration without rendering.
@@ -35,6 +47,15 @@ export function renderWithThemeToml(input: string, themeToml: string, width?: nu
  */
 export function validate(input: string): void;
 
+/**
+ * Returns a one-paragraph text equivalent of a TOML or JSON declaration — the text the
+ * rendered SVG carries as its `<desc>`. Use it as `alt` when the SVG is shown through `<img>`.
+ * @param input - TOML or JSON declaration string
+ * @returns Text equivalent, e.g. `"Process: Upload → Parse → Index."`
+ * @throws If the declaration is invalid
+ */
+export function describe(input: string): string;
+
 /**
  * Returns the list of supported theme names.
  */

package/index.js

@@ -3,22 +3,23 @@ import {
   render_json,
   render_with_theme_toml,
   validate,
+  describe,
   themes as wasmThemes,
   kinds as wasmKinds,
 } from './wasm/declart_wasm.js';
 
-export { validate };
+export { validate, describe };
 
-export function render(input, theme = 'default', width) {
-  return wasmRender(input, theme, width ?? undefined);
+export function render(input, theme = 'default', width, options) {
+  return wasmRender(input, theme, width ?? undefined, options?.transparent ?? undefined);
 }
 
-export function renderJson(input, theme = 'default', width) {
-  return render_json(input, theme, width ?? undefined);
+export function renderJson(input, theme = 'default', width, options) {
+  return render_json(input, theme, width ?? undefined, options?.transparent ?? undefined);
 }
 
-export function renderWithThemeToml(input, themeToml, width) {
-  return render_with_theme_toml(input, themeToml, width ?? undefined);
+export function renderWithThemeToml(input, themeToml, width, options) {
+  return render_with_theme_toml(input, themeToml, width ?? undefined, options?.transparent ?? undefined);
 }
 
 export function themes() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/declart-web",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Declarative diagram engine for browsers and bundlers (Vite, webpack, Rollup) — declare what to show, the engine renders SVG",
   "license": "MIT",
   "type": "module",

package/wasm/declart_wasm.d.ts

@@ -1,6 +1,14 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * Returns a one-paragraph text equivalent of a TOML or JSON declaration — the same text the
+ * rendered SVG carries as `<desc>`. Use it as `alt` when the SVG is shown through `<img>`.
+ *
+ * Returns a `JsError` with the parse/validation error message when the declaration is invalid.
+ */
+export function describe(input: string): string;
+
 /**
  * Returns a comma-separated list of supported diagram kind names.
  */
@@ -12,10 +20,11 @@ export function kinds(): string;
  * - `input`: TOML or JSON declaration string (auto-detected by leading `{`)
  * - `theme`: `"default"`, `"monochrome"`, `"accessible"`, or `"warm"` (unknown values fall back to `"default"`)
  * - `width`: optional canvas width in pixels (height scales proportionally)
+ * - `transparent`: `Some(true)` leaves the backdrop unpainted so the page shows through
  *
  * Returns the SVG string on success, or a `JsError` with a descriptive message on failure.
  */
-export function render(input: string, theme: string, width?: number | null): string;
+export function render(input: string, theme: string, width?: number | null, transparent?: boolean | null): string;
 
 /**
  * Renders a JSON diagram declaration to SVG with a named theme.
@@ -26,7 +35,7 @@ export function render(input: string, theme: string, width?: number | null): str
  *
  * Returns the SVG string on success, or a `JsError` on failure.
  */
-export function render_json(input: string, theme: string, width?: number | null): string;
+export function render_json(input: string, theme: string, width?: number | null, transparent?: boolean | null): string;
 
 /**
  * Renders a TOML or JSON diagram declaration with a custom theme defined as a TOML string.
@@ -37,7 +46,7 @@ export function render_json(input: string, theme: string, width?: number | null)
  *
  * Returns the SVG string on success, or a `JsError` on parse/validation failure.
  */
-export function render_with_theme_toml(input: string, theme_toml: string, width?: number | null): string;
+export function render_with_theme_toml(input: string, theme_toml: string, width?: number | null, transparent?: boolean | null): string;
 
 /**
  * Returns a comma-separated list of supported theme names.

package/wasm/declart_wasm.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./declart_wasm_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    kinds, render, render_json, render_with_theme_toml, themes, validate
+    describe, kinds, render, render_json, render_with_theme_toml, themes, validate
 } from "./declart_wasm_bg.js";

package/wasm/declart_wasm_bg.js

@@ -1,3 +1,32 @@
+/**
+ * Returns a one-paragraph text equivalent of a TOML or JSON declaration — the same text the
+ * rendered SVG carries as `<desc>`. Use it as `alt` when the SVG is shown through `<img>`.
+ *
+ * Returns a `JsError` with the parse/validation error message when the declaration is invalid.
+ * @param {string} input
+ * @returns {string}
+ */
+export function describe(input) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.describe(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Returns a comma-separated list of supported diagram kind names.
  * @returns {string}
@@ -21,14 +50,16 @@ export function kinds() {
  * - `input`: TOML or JSON declaration string (auto-detected by leading `{`)
  * - `theme`: `"default"`, `"monochrome"`, `"accessible"`, or `"warm"` (unknown values fall back to `"default"`)
  * - `width`: optional canvas width in pixels (height scales proportionally)
+ * - `transparent`: `Some(true)` leaves the backdrop unpainted so the page shows through
  *
  * Returns the SVG string on success, or a `JsError` with a descriptive message on failure.
  * @param {string} input
  * @param {string} theme
  * @param {number | null} [width]
+ * @param {boolean | null} [transparent]
  * @returns {string}
  */
-export function render(input, theme, width) {
+export function render(input, theme, width, transparent) {
     let deferred4_0;
     let deferred4_1;
     try {
@@ -36,7 +67,7 @@ export function render(input, theme, width) {
         const len0 = WASM_VECTOR_LEN;
         const ptr1 = passStringToWasm0(theme, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len1 = WASM_VECTOR_LEN;
-        const ret = wasm.render(ptr0, len0, ptr1, len1, isLikeNone(width) ? Number.MAX_SAFE_INTEGER : (width) >>> 0);
+        const ret = wasm.render(ptr0, len0, ptr1, len1, isLikeNone(width) ? Number.MAX_SAFE_INTEGER : (width) >>> 0, isLikeNone(transparent) ? 0xFFFFFF : transparent ? 1 : 0);
         var ptr3 = ret[0];
         var len3 = ret[1];
         if (ret[3]) {
@@ -62,9 +93,10 @@ export function render(input, theme, width) {
  * @param {string} input
  * @param {string} theme
  * @param {number | null} [width]
+ * @param {boolean | null} [transparent]
  * @returns {string}
  */
-export function render_json(input, theme, width) {
+export function render_json(input, theme, width, transparent) {
     let deferred4_0;
     let deferred4_1;
     try {
@@ -72,7 +104,7 @@ export function render_json(input, theme, width) {
         const len0 = WASM_VECTOR_LEN;
         const ptr1 = passStringToWasm0(theme, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len1 = WASM_VECTOR_LEN;
-        const ret = wasm.render_json(ptr0, len0, ptr1, len1, isLikeNone(width) ? Number.MAX_SAFE_INTEGER : (width) >>> 0);
+        const ret = wasm.render_json(ptr0, len0, ptr1, len1, isLikeNone(width) ? Number.MAX_SAFE_INTEGER : (width) >>> 0, isLikeNone(transparent) ? 0xFFFFFF : transparent ? 1 : 0);
         var ptr3 = ret[0];
         var len3 = ret[1];
         if (ret[3]) {
@@ -98,9 +130,10 @@ export function render_json(input, theme, width) {
  * @param {string} input
  * @param {string} theme_toml
  * @param {number | null} [width]
+ * @param {boolean | null} [transparent]
  * @returns {string}
  */
-export function render_with_theme_toml(input, theme_toml, width) {
+export function render_with_theme_toml(input, theme_toml, width, transparent) {
     let deferred4_0;
     let deferred4_1;
     try {
@@ -108,7 +141,7 @@ export function render_with_theme_toml(input, theme_toml, width) {
         const len0 = WASM_VECTOR_LEN;
         const ptr1 = passStringToWasm0(theme_toml, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len1 = WASM_VECTOR_LEN;
-        const ret = wasm.render_with_theme_toml(ptr0, len0, ptr1, len1, isLikeNone(width) ? Number.MAX_SAFE_INTEGER : (width) >>> 0);
+        const ret = wasm.render_with_theme_toml(ptr0, len0, ptr1, len1, isLikeNone(width) ? Number.MAX_SAFE_INTEGER : (width) >>> 0, isLikeNone(transparent) ? 0xFFFFFF : transparent ? 1 : 0);
         var ptr3 = ret[0];
         var len3 = ret[1];
         if (ret[3]) {

package/wasm/declart_wasm_bg.wasm.d.ts

@@ -1,15 +1,16 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const describe: (a: number, b: number) => [number, number, number, number];
 export const kinds: () => [number, number];
-export const render: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
-export const render_json: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
-export const render_with_theme_toml: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+export const render: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
+export const render_json: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
+export const render_with_theme_toml: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
 export const themes: () => [number, number];
 export const validate: (a: number, b: number) => [number, number];
 export const __wbindgen_externrefs: WebAssembly.Table;
-export const __wbindgen_free: (a: number, b: number, c: number) => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
 export const __wbindgen_start: () => void;