@iyulab/declart 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

@@ -7,10 +7,11 @@ const wasm = require('./wasm/declart_wasm');
  * @param {string} input - TOML or JSON declaration string (auto-detected)
  * @param {string} [theme='default'] - Theme name: 'default', 'monochrome', 'accessible', 'warm'
  * @param {number} [width] - Optional canvas width in pixels
+ * @param {{ transparent?: boolean }} [options] - `transparent: true` leaves the backdrop unpainted
  * @returns {string} SVG string
  */
-function render(input, theme = 'default', width) {
-    return wasm.render(input, theme, width ?? null);
+function render(input, theme = 'default', width, options) {
+    return wasm.render(input, theme, width ?? null, options?.transparent ?? null);
 }
 
 /**
@@ -18,10 +19,11 @@ function render(input, theme = 'default', width) {
  * @param {string} input - JSON declaration string
  * @param {string} [theme='default'] - Theme name
  * @param {number} [width] - Optional canvas width in pixels
+ * @param {{ transparent?: boolean }} [options] - `transparent: true` leaves the backdrop unpainted
  * @returns {string} SVG string
  */
-function renderJson(input, theme = 'default', width) {
-    return wasm.render_json(input, theme, width ?? null);
+function renderJson(input, theme = 'default', width, options) {
+    return wasm.render_json(input, theme, width ?? null, options?.transparent ?? null);
 }
 
 /**
@@ -29,10 +31,11 @@ function renderJson(input, theme = 'default', width) {
  * @param {string} input - TOML or JSON declaration string
  * @param {string} themeToml - TOML theme definition string
  * @param {number} [width] - Optional canvas width in pixels
+ * @param {{ transparent?: boolean }} [options] - `transparent: true` leaves the backdrop unpainted
  * @returns {string} SVG string
  */
-function renderWithThemeToml(input, themeToml, width) {
-    return wasm.render_with_theme_toml(input, themeToml, width ?? null);
+function renderWithThemeToml(input, themeToml, width, options) {
+    return wasm.render_with_theme_toml(input, themeToml, width ?? null, options?.transparent ?? null);
 }
 
 /**
@@ -44,6 +47,17 @@ function validate(input) {
     return wasm.validate(input);
 }
 
+/**
+ * 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 {string} input - TOML or JSON declaration string
+ * @returns {string} Text equivalent
+ * @throws {Error} If the declaration is invalid
+ */
+function describe(input) {
+    return wasm.describe(input);
+}
+
 /**
  * Returns the list of supported theme names.
  * @returns {string[]}
@@ -60,4 +74,4 @@ function kinds() {
     return wasm.kinds().split(',');
 }
 
-module.exports = { render, renderJson, renderWithThemeToml, validate, themes, kinds };
+module.exports = { render, renderJson, renderWithThemeToml, validate, describe, themes, kinds };

package/index.mjs

@@ -8,5 +8,6 @@ export const render = declart.render;
 export const renderJson = declart.renderJson;
 export const renderWithThemeToml = declart.renderWithThemeToml;
 export const validate = declart.validate;
+export const describe = declart.describe;
 export const themes = declart.themes;
 export const kinds = declart.kinds;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/declart",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Declarative diagram engine for Node.js — declare what to show, the engine renders SVG",
   "license": "MIT",
   "repository": {

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

@@ -1,5 +1,35 @@
 /* @ts-self-types="./declart_wasm.d.ts" */
 
+/**
+ * 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}
+ */
+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);
+    }
+}
+exports.describe = describe;
+
 /**
  * Returns a comma-separated list of supported diagram kind names.
  * @returns {string}
@@ -24,14 +54,16 @@ exports.kinds = 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}
  */
-function render(input, theme, width) {
+function render(input, theme, width, transparent) {
     let deferred4_0;
     let deferred4_1;
     try {
@@ -39,7 +71,7 @@ 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]) {
@@ -66,9 +98,10 @@ exports.render = render;
  * @param {string} input
  * @param {string} theme
  * @param {number | null} [width]
+ * @param {boolean | null} [transparent]
  * @returns {string}
  */
-function render_json(input, theme, width) {
+function render_json(input, theme, width, transparent) {
     let deferred4_0;
     let deferred4_1;
     try {
@@ -76,7 +109,7 @@ 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]) {
@@ -103,9 +136,10 @@ exports.render_json = render_json;
  * @param {string} input
  * @param {string} theme_toml
  * @param {number | null} [width]
+ * @param {boolean | null} [transparent]
  * @returns {string}
  */
-function render_with_theme_toml(input, theme_toml, width) {
+function render_with_theme_toml(input, theme_toml, width, transparent) {
     let deferred4_0;
     let deferred4_1;
     try {
@@ -113,7 +147,7 @@ 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]) {