@formulaxjs/renderer-kity 0.2.0

package/LICENSE

@@ -0,0 +1,35 @@
+# MIT License
+
+Copyright (c) 2024 FormulaX Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+## Legacy KityFormula Code
+
+Portions of FormulaX, specifically within the `@formulaxjs/kity-runtime` package,
+contain code adapted from [KityFormula](https://github.com/BaiduFE/kityformula)
+by Baidu FEX Team, originally released under the MIT License.
+
+KityFormula-related code in FormulaX is retained under the same MIT License
+and is subject to the copyright notice above.
+
+For details on the original KityFormula project, see:
+https://github.com/BaiduFE/kityformula

package/README.md

@@ -0,0 +1,46 @@
+# @formulaxjs/renderer-kity
+
+Kity-based read-only renderer for FormulaX.
+
+`@formulaxjs/renderer-kity` turns LaTeX into inline SVG markup by using the legacy Kity runtime behind the shared `@formulaxjs/renderer` contract. It is the current concrete renderer package for adapters that want runtime SVG output without depending on editor UI helpers.
+
+> Status: experimental. Public APIs may change before the first stable release.
+
+## Install
+
+```bash
+pnpm add @formulaxjs/renderer-kity
+```
+
+## Highlights
+
+- `createKityFormulaRenderer`
+- `renderLatexToSvgMarkup`
+- `serializeKityFormulaFromRoot`
+- `waitForKityFormulaSvgLayout`
+- cache-safe asset overrides through `assetsVersion`
+
+## Example
+
+```ts
+import { createKityFormulaRenderer } from '@formulaxjs/renderer-kity';
+
+const renderer = createKityFormulaRenderer({
+  fontSize: 40,
+});
+
+const result = await renderer.renderLatex('\\frac{a}{b}');
+
+console.log(result.engine); // kity
+console.log(result.html);   // inline SVG markup
+```
+
+If you pass custom runtime asset overrides and want caching to stay enabled, also pass an `assetsVersion` string so different asset sets do not share the same cache entry.
+
+## Package role
+
+Use this package when you want a concrete FormulaX renderer implementation today.
+
+- It depends on `@formulaxjs/renderer` for shared renderer contracts and SVG helpers.
+- It depends on `@formulaxjs/kity-runtime` for the legacy Kity backend.
+- It does not depend on `@formulaxjs/editor`.

package/dist/editor-JT5KLVXX.css

@@ -0,0 +1,3 @@
+@import url('./base.css');
+@import url('./ui.css');
+@import url('./scrollbar.css');

package/dist/index.cjs

@@ -0,0 +1,188 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createKityFormulaRenderer: () => createKityFormulaRenderer,
+  findKityFormulaSvg: () => findKityFormulaSvg,
+  renderLatexToSvgMarkup: () => renderLatexToSvgMarkup,
+  serializeKityFormulaFromRoot: () => serializeKityFormulaFromRoot,
+  waitForKityFormulaSvgLayout: () => waitForKityFormulaSvgLayout
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/renderer.ts
+var import_renderer2 = require("@formulaxjs/renderer");
+var import_kity_runtime = require("@formulaxjs/kity-runtime");
+
+// src/dom.ts
+function createHiddenRenderHost(doc = document) {
+  const host = doc.createElement("div");
+  host.style.position = "fixed";
+  host.style.left = "-100000px";
+  host.style.top = "0";
+  host.style.width = "1px";
+  host.style.height = "1px";
+  host.style.opacity = "0";
+  host.style.pointerEvents = "none";
+  host.setAttribute("aria-hidden", "true");
+  doc.body.appendChild(host);
+  return host;
+}
+async function waitForDocumentFonts(doc) {
+  if (!doc.fonts?.ready) return;
+  try {
+    await doc.fonts.ready;
+  } catch {
+  }
+}
+function waitForAnimationFrame(view) {
+  return new Promise((resolve) => {
+    view.requestAnimationFrame(() => resolve());
+  });
+}
+
+// src/serialize.ts
+var import_renderer = require("@formulaxjs/renderer");
+function findKityFormulaSvg(root) {
+  return root.querySelector(
+    ".kf-editor-edit-area svg, .kf-editor-canvas-container svg, svg"
+  );
+}
+function serializeKityFormulaFromRoot(root) {
+  const svg = findKityFormulaSvg(root);
+  if (!svg) {
+    return "";
+  }
+  return (0, import_renderer.serializeSvgForInsertion)(svg);
+}
+async function waitForKityFormulaSvgLayout(root) {
+  const doc = root.ownerDocument ?? document;
+  const view = doc.defaultView ?? window;
+  await waitForDocumentFonts(doc);
+  let previous = readRenderedFormulaBox(root);
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    await waitForAnimationFrame(view);
+    const current = readRenderedFormulaBox(root);
+    if (previous && current && areSvgBoxesClose(previous, current)) {
+      return;
+    }
+    previous = current;
+  }
+}
+function readRenderedFormulaBox(root) {
+  const svg = findKityFormulaSvg(root);
+  if (!svg) {
+    return null;
+  }
+  return (0, import_renderer.readRenderedFormulaSvgBox)(svg);
+}
+function areSvgBoxesClose(left, right) {
+  return Math.abs(left.x - right.x) < 0.01 && Math.abs(left.y - right.y) < 0.01 && Math.abs(left.width - right.width) < 0.01 && Math.abs(left.height - right.height) < 0.01;
+}
+
+// src/renderer.ts
+var renderCache = /* @__PURE__ */ new Map();
+function hasCustomAssetOverrides(assets) {
+  return Boolean(assets && Object.keys(assets).length > 0);
+}
+function createKityFormulaRenderer(defaults = {}) {
+  return {
+    renderLatex(latex, options = {}) {
+      return renderLatexToSvgMarkup(latex, {
+        ...defaults,
+        ...options
+      });
+    }
+  };
+}
+function renderLatexToSvgMarkup(latex, options = {}) {
+  const normalizedLatex = latex.trim();
+  const shouldUseCache = options.cache !== false && !(hasCustomAssetOverrides(options.assets) && !options.assetsVersion);
+  if (!normalizedLatex) {
+    return Promise.resolve({
+      engine: "kity",
+      output: "svg",
+      latex: normalizedLatex,
+      html: ""
+    });
+  }
+  const cacheKey = (0, import_renderer2.createFormulaRenderCacheKey)({
+    engine: "kity",
+    latex: normalizedLatex,
+    output: "svg",
+    fontSize: options.fontSize,
+    displayMode: options.displayMode,
+    className: options.className,
+    assetsVersion: options.assetsVersion
+  });
+  if (shouldUseCache) {
+    const cached = renderCache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+  }
+  const pending = renderLatexToSvgMarkupUncached(normalizedLatex, options);
+  if (shouldUseCache) {
+    renderCache.set(cacheKey, pending);
+    pending.catch(() => {
+      if (renderCache.get(cacheKey) === pending) {
+        renderCache.delete(cacheKey);
+      }
+    });
+  }
+  return pending;
+}
+async function renderLatexToSvgMarkupUncached(latex, options) {
+  if (typeof document === "undefined") {
+    throw new Error("Kity renderer requires a browser document.");
+  }
+  const host = createHiddenRenderHost(document);
+  const handle = await (0, import_kity_runtime.mountKityEditor)(host, {
+    initialLatex: latex,
+    height: options.height ?? "100%",
+    autofocus: false,
+    assets: options.assets,
+    render: {
+      fontsize: options.fontSize ?? 40
+    }
+  });
+  try {
+    await waitForKityFormulaSvgLayout(host);
+    return {
+      engine: "kity",
+      output: "svg",
+      latex,
+      html: serializeKityFormulaFromRoot(host)
+    };
+  } finally {
+    handle.destroy();
+    host.remove();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createKityFormulaRenderer,
+  findKityFormulaSvg,
+  renderLatexToSvgMarkup,
+  serializeKityFormulaFromRoot,
+  waitForKityFormulaSvgLayout
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/renderer.ts","../src/dom.ts","../src/serialize.ts"],"sourcesContent":["export type { KityFormulaRenderOptions } from './types';\n\nexport {\n  createKityFormulaRenderer,\n  renderLatexToSvgMarkup,\n} from './renderer';\n\nexport {\n  findKityFormulaSvg,\n  serializeKityFormulaFromRoot,\n  waitForKityFormulaSvgLayout,\n} from './serialize';\n","import {\n  createFormulaRenderCacheKey,\n  type FormulaRenderer,\n  type FormulaRenderResult,\n} from '@formulaxjs/renderer';\nimport { mountKityEditor, type KityEditorAssets } from '@formulaxjs/kity-runtime';\nimport { createHiddenRenderHost } from './dom';\nimport {\n  serializeKityFormulaFromRoot,\n  waitForKityFormulaSvgLayout,\n} from './serialize';\nimport type { KityFormulaRenderOptions } from './types';\n\nconst renderCache = new Map<string, Promise<FormulaRenderResult>>();\n\nfunction hasCustomAssetOverrides(assets?: Partial<KityEditorAssets>): boolean {\n  return Boolean(assets && Object.keys(assets).length > 0);\n}\n\nexport function createKityFormulaRenderer(\n  defaults: KityFormulaRenderOptions = {},\n): FormulaRenderer {\n  return {\n    renderLatex(latex, options = {}) {\n      return renderLatexToSvgMarkup(latex, {\n        ...defaults,\n        ...options,\n      });\n    },\n  };\n}\n\nexport function renderLatexToSvgMarkup(\n  latex: string,\n  options: KityFormulaRenderOptions = {},\n): Promise<FormulaRenderResult> {\n  const normalizedLatex = latex.trim();\n  const shouldUseCache = options.cache !== false\n    && !(hasCustomAssetOverrides(options.assets) && !options.assetsVersion);\n\n  if (!normalizedLatex) {\n    return Promise.resolve({\n      engine: 'kity',\n      output: 'svg',\n      latex: normalizedLatex,\n      html: '',\n    });\n  }\n\n  const cacheKey = createFormulaRenderCacheKey({\n    engine: 'kity',\n    latex: normalizedLatex,\n    output: 'svg',\n    fontSize: options.fontSize,\n    displayMode: options.displayMode,\n    className: options.className,\n    assetsVersion: options.assetsVersion,\n  });\n\n  if (shouldUseCache) {\n    const cached = renderCache.get(cacheKey);\n    if (cached) {\n      return cached;\n    }\n  }\n\n  const pending = renderLatexToSvgMarkupUncached(normalizedLatex, options);\n\n  if (shouldUseCache) {\n    renderCache.set(cacheKey, pending);\n    pending.catch(() => {\n      if (renderCache.get(cacheKey) === pending) {\n        renderCache.delete(cacheKey);\n      }\n    });\n  }\n\n  return pending;\n}\n\nasync function renderLatexToSvgMarkupUncached(\n  latex: string,\n  options: KityFormulaRenderOptions,\n): Promise<FormulaRenderResult> {\n  if (typeof document === 'undefined') {\n    throw new Error('Kity renderer requires a browser document.');\n  }\n\n  const host = createHiddenRenderHost(document);\n  const handle = await mountKityEditor(host, {\n    initialLatex: latex,\n    height: options.height ?? '100%',\n    autofocus: false,\n    assets: options.assets,\n    render: {\n      fontsize: options.fontSize ?? 40,\n    },\n  });\n\n  try {\n    await waitForKityFormulaSvgLayout(host);\n\n    return {\n      engine: 'kity',\n      output: 'svg',\n      latex,\n      html: serializeKityFormulaFromRoot(host),\n    };\n  } finally {\n    handle.destroy();\n    host.remove();\n  }\n}\n","export function createHiddenRenderHost(doc: Document = document): HTMLElement {\n  const host = doc.createElement('div');\n\n  host.style.position = 'fixed';\n  host.style.left = '-100000px';\n  host.style.top = '0';\n  host.style.width = '1px';\n  host.style.height = '1px';\n  host.style.opacity = '0';\n  host.style.pointerEvents = 'none';\n  host.setAttribute('aria-hidden', 'true');\n\n  doc.body.appendChild(host);\n\n  return host;\n}\n\nexport async function waitForDocumentFonts(doc: Document): Promise<void> {\n  if (!doc.fonts?.ready) return;\n\n  try {\n    await doc.fonts.ready;\n  } catch {\n    // Ignore font readiness failures and fall back to frame-based settling.\n  }\n}\n\nexport function waitForAnimationFrame(view: Window): Promise<void> {\n  return new Promise((resolve) => {\n    view.requestAnimationFrame(() => resolve());\n  });\n}\n","import {\n  readRenderedFormulaSvgBox,\n  serializeSvgForInsertion,\n  type SvgBox,\n} from '@formulaxjs/renderer';\nimport { waitForAnimationFrame, waitForDocumentFonts } from './dom';\n\nexport function findKityFormulaSvg(root: HTMLElement): SVGSVGElement | null {\n  return root.querySelector<SVGSVGElement>(\n    '.kf-editor-edit-area svg, .kf-editor-canvas-container svg, svg',\n  );\n}\n\nexport function serializeKityFormulaFromRoot(root: HTMLElement): string {\n  const svg = findKityFormulaSvg(root);\n\n  if (!svg) {\n    return '';\n  }\n\n  return serializeSvgForInsertion(svg);\n}\n\nexport async function waitForKityFormulaSvgLayout(root: HTMLElement): Promise<void> {\n  const doc = root.ownerDocument ?? document;\n  const view = doc.defaultView ?? window;\n\n  await waitForDocumentFonts(doc);\n\n  let previous = readRenderedFormulaBox(root);\n\n  for (let attempt = 0; attempt < 4; attempt += 1) {\n    await waitForAnimationFrame(view);\n    const current = readRenderedFormulaBox(root);\n\n    if (previous && current && areSvgBoxesClose(previous, current)) {\n      return;\n    }\n\n    previous = current;\n  }\n}\n\nfunction readRenderedFormulaBox(root: HTMLElement): SvgBox | null {\n  const svg = findKityFormulaSvg(root);\n\n  if (!svg) {\n    return null;\n  }\n\n  return readRenderedFormulaSvgBox(svg);\n}\n\nfunction areSvgBoxesClose(left: SvgBox, right: SvgBox): boolean {\n  return Math.abs(left.x - right.x) < 0.01\n    && Math.abs(left.y - right.y) < 0.01\n    && Math.abs(left.width - right.width) < 0.01\n    && Math.abs(left.height - right.height) < 0.01;\n}\n"],"mappings":"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","names":["import_renderer"]}