API reference

render(text, config?)

Renders a DSL string into an SVG string. Dispatches by first keyword and throws when detection, parsing, layout, or rendering fails.

import { render } from 'schematex';

const svg: string = render(text, { theme: 'monochrome' });

Use the strict API when invalid DSL must stop the workflow, for example during a test, export job, or server-side validation gate.

parse(text, config?)

Parses a DSL string into the typed AST without rendering. This API is also strict and throws on invalid DSL.

import { parse } from 'schematex';

const ast = parse(text);

Preview-safe rendering

Live editors, AI previews, and chat canvases should not turn a parser failure into an empty surface. Use renderPreview() when you only need an SVG string:

import { renderPreview } from 'schematex';

const svg = renderPreview(text, { type: 'circuit' });

renderPreview() always returns SVG. If strict rendering fails, that SVG is a visible diagnostic fallback. render(text, { mode: 'preview' }) is the same preview boundary for integrations that already call render().

Result APIs

Use result APIs when the caller needs both a visible output and validity state:

import { parseResult, renderResult } from 'schematex';

const renderState = renderResult(text);
container.innerHTML = renderState.svg;

if (!renderState.ok) {
  console.error(renderState.diagnostics);
}

const parseState = parseResult(text);

renderResult() returns svg, diagnostics, type, and a status of valid, partial, or invalid. Invalid render results still carry a diagnostic SVG so the preview remains visible.

parseResult() returns either an AST or structured diagnostics without throwing. The partial status is reserved for parsers that can recover a partial AST or partial rendered diagram.

Do not treat "an SVG string exists" as proof that the DSL is valid. Preview surfaces should show the SVG and use ok, status, and diagnostics for retry, repair, telemetry, or billing decisions.

Browser and React

The browser subpath exposes strict DOM helpers and preview-safe DOM helpers:

import {
  renderToContainer,
  renderPreviewToContainer,
} from 'schematex/browser';

renderToContainer(text, exportContainer);          // strict
renderPreviewToContainer(text, previewContainer);  // visible fallback

Use the small read-only React component when the canvas should not modify DSL:

import { SchematexDiagram } from 'schematex/react';

<SchematexDiagram
  dsl={text}
  type="circuit"
  onError={(error) => console.error(error)}
/>;

onError fires on strict parser/layout/render failure before the component shows the diagnostic fallback SVG.

For a controlled editor, use InteractiveSchematexDiagram:

'use client';

import { useState } from 'react';
import { InteractiveSchematexDiagram } from 'schematex/react';

export function DiagramEditor({ initialDsl }: { initialDsl: string }) {
  const [dsl, setDsl] = useState(initialDsl);
  return (
    <InteractiveSchematexDiagram
      value={dsl}
      onChange={(nextDsl, detail) => {
        setDsl(nextDsl);
        console.log(detail.reason, detail.item?.semanticId);
      }}
      debounceMs={120}
      canvasClassName="diagramCanvas"
    />
  );
}

This component is controlled: persistence, undo, source-code editing, and collaboration stay in your application. canvasClassName applies to the inner host <div> that directly contains the generated SVG; it does not mutate the SVG's class attribute. See Interactive editing for the complete Props table, styling contract, event semantics, capability discovery, and Vanilla DOM API.

Tree-shakable imports

import { render } from 'schematex/genogram';
import { render } from 'schematex/ecomap';
import { render } from 'schematex/pedigree';
import { render } from 'schematex/phylo';
import { render } from 'schematex/sociogram';

SchematexConfig

interface SchematexConfig {
  type?: string;              // optional diagram type override
  width?: number;
  height?: number;
  padding?: number;
  theme?: string;             // e.g. 'default' | 'monochrome' | 'dark'
  fontFamily?: string;
  mode?: 'strict' | 'preview';
  scene?: boolean;            // include editable SceneItem metadata
}

See src/core/types.ts and src/core/api.ts for the complete type definitions.