@drawmotive/textgraph 0.1.0-alpha.1 → 0.2.0

package/src/react/index.d.ts

@@ -0,0 +1,19 @@
+import type { ImgHTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { TextGraphInitializeOptions, TextGraphRenderPngOptions } from '../index.js';
+
+/** Keep options stable (module constant or useMemo); replacing them replaces the runtime. */
+export interface TextGraphProviderProps {
+  options?: TextGraphInitializeOptions;
+  children?: ReactNode;
+}
+
+/** The component owns its image source and cancellation; other image attributes pass through. */
+export interface TextGraphProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet' | 'children' | 'loading'> {
+  source: string;
+  alt?: string;
+  renderOptions?: Omit<TextGraphRenderPngOptions, 'encoding' | 'signal'>;
+  loading?: ReactNode;
+}
+
+export declare function TextGraphProvider(props: TextGraphProviderProps): ReactElement;
+export declare function TextGraph(props: TextGraphProps): ReactElement;

package/src/react/index.js

@@ -0,0 +1,56 @@
+'use client';
+
+import { createContext, createElement, useContext, useEffect, useMemo, useState } from 'react';
+import { createRuntimeResource } from './runtime.js';
+
+const RuntimeContext = createContext(null);
+const defaultOptions = Object.freeze({});
+
+/** Shares a lazy browser runtime across diagrams and owns its eventual disposal. */
+export function TextGraphProvider({ options = defaultOptions, children }) {
+  const resource = useMemo(() => createRuntimeResource(options), [options]);
+  useEffect(() => resource.retain(), [resource]);
+  return createElement(RuntimeContext.Provider, { value: resource }, children);
+}
+
+/** Renders DSL as an image; only the latest committed input may publish a result. */
+export function TextGraph({ source, alt = 'TextGraph diagram', renderOptions = defaultOptions,
+  loading = 'Rendering diagram…', ...imageProps }) {
+  const shared = useContext(RuntimeContext);
+  const resource = useMemo(() => shared ?? createRuntimeResource(defaultOptions), [shared]);
+  const { scale, padding, maxWidth } = renderOptions;
+  const request = useMemo(() => ({ source, scale, padding, maxWidth, resource }),
+    [source, scale, padding, maxWidth, resource]);
+  const [state, setState] = useState(null);
+
+  useEffect(() => {
+    const release = resource.retain();
+    const controller = new AbortController();
+    void (async () => {
+      try {
+        const runtime = await resource.get();
+        if (controller.signal.aborted) return;
+        const result = await runtime.renderPng(source, { scale, padding, maxWidth, encoding: 'base64', signal: controller.signal });
+        if (!controller.signal.aborted) setState({ request, result });
+      } catch (error) {
+        if (!controller.signal.aborted) {
+          // Host loaders may reject arbitrary values, including null. Keep the
+          // failure branch explicit so reporting an error cannot break React render.
+          setState({ request, error: error instanceof Error ? error : new Error(String(error ?? 'Could not render diagram')) });
+        }
+      }
+    })();
+    return () => { controller.abort(); release(); };
+  }, [request]);
+
+  // State is keyed by the whole request so old images disappear immediately,
+  // even before passive effects clean up the previous asynchronous render.
+  if (state?.request !== request) return createElement('span', { role: 'status' }, loading);
+  if (state.error || !state.result.success) {
+    const message = state.error?.message ?? state.result.diagnostics.map(item => item.message).join('\n');
+    return createElement('span', { role: 'alert' }, message || 'Could not render diagram');
+  }
+  const result = state.result;
+  return createElement('img', { width: result.width, height: result.height, ...imageProps,
+    src: `data:image/png;base64,${result.png}`, alt });
+}

package/src/react/runtime.js

@@ -0,0 +1,37 @@
+import { initializeTextGraph } from '../platform/browser.js';
+
+/** A provider owns one lazy runtime; retaining it has no I/O during React render. */
+export function createRuntimeResource(options) {
+  let users = 0;
+  let pending;
+  return {
+    retain() {
+      users++;
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        users--;
+        // StrictMode replays effects synchronously. Defer final release so that
+        // replay reuses the same .NET module graph instead of starting another.
+        queueMicrotask(() => {
+          if (users !== 0 || !pending) return;
+          const retiring = pending;
+          pending = undefined;
+          // Startup may finish after unmount. Dispose that instance as well;
+          // there is no mounted view to receive startup or cleanup errors.
+          void retiring.then(runtime => runtime.dispose()).catch(() => undefined);
+        });
+      };
+    },
+    get() {
+      if (!pending) {
+        const attempt = initializeTextGraph(options);
+        pending = attempt;
+        // A later input change may retry a failed startup.
+        void attempt.catch(() => { if (pending === attempt) pending = undefined; });
+      }
+      return pending;
+    },
+  };
+}