@datagrok-libraries/hwe

A standalone TypeScript HELM Web Editor — parse, render, edit, and compute on biopolymers (peptides, RNA/DNA, CHEM, conjugates) written in HELM notation. No framework, no DOM globals required: a headless service for parsing/rendering/calculations, plus a full interactive editor you can drop into any page.

Features

• Parser & serializer — HELM V2.0 in/out, lenient or strict, with structured validation diagnostics.
• Renderer — crisp SVG (and canvas) drawing: monomer shapes, bonds, cyclic/branched layouts, RNA cloverleaves, 5′/3′ direction markers, serpentine wrapping for long chains.
• Interactive editor — palette, toolbar, drag-to-add, bond/monomer dialogs, undo/redo, zoom/pan, find & replace, light/dark themes.
• Calculations — molecular formula, weight, extinction coefficient, pseudo-molfile.
• Headless — every non-interactive feature runs in Node (SSR, batch, grid cell rendering) with no browser.
• Datagrok adapter — drop-in integration via the @datagrok-libraries/hwe/datagrok entry point.

Install

npm install @datagrok-libraries/hwe

Ships as ESM + CJS with TypeScript declarations.

Quick start

Headless: parse, render, compute

import { HelmService, MonomerLib } from '@datagrok-libraries/hwe';

// Load a monomer library (HELMCoreLibrary JSON, your own, or empty()).
const lib = MonomerLib.empty();              // or MonomerLib.fromText(json)
const svc = new HelmService({ monomerLib: lib });

const helm = 'PEPTIDE1{A.C.D.E.F.G}$$$$';

const svg = svc.renderToSvg(helm, { width: 600, height: 200 });
const { mol, diagnostics } = svc.parse(helm);
const issues = svc.validate(helm);           // ValidationDiagnostic[]
const weight = svc.getMolWeight(helm);       // needs a real library for accuracy
const formula = svc.getFormula(helm);

Calculations and atomic structures need a real monomer library (weights are 0 against empty()). Load one with MonomerLib.fromText(json), MonomerLib.fromJSON(obj), or await MonomerLib.fromUrl(url).

Interactive editor

import { HelmService, MonomerLib, HelmEditorApp } from '@datagrok-libraries/hwe';
import '@datagrok-libraries/hwe/styles.css';   // editor stylesheet

const lib = await MonomerLib.fromUrl('/HELMCoreLibrary.json');
const service = new HelmService({ monomerLib: lib });

const app = new HelmEditorApp(document.getElementById('editor')!, {
  service,
  initialHelm: 'PEPTIDE1{A.C.D.E.F.G}$$$$',
});

app.setHelm('RNA1{r(A)p.r(C)p.r(G)p.r(U)p}$$$$V2.0');
const current = app.getHelm();                // read it back

The editor surfaces structure (atomic) previews on hover when you pass an RDKit module to the service:

const service = new HelmService({ monomerLib: lib, rdkitModule });

Theming

import { lightTheme, darkTheme, defineTheme } from '@datagrok-libraries/hwe';

new HelmEditorApp(host, { service, theme: darkTheme });

Datagrok

The @datagrok-libraries/hwe/datagrok entry exposes the adapter used by the Datagrok Helm package (helper registration, editor/app/input wrappers, monomer-library bridge):

import { registerWithDatagrok } from '@datagrok-libraries/hwe/datagrok';

const { adapter, unsubscribe } = registerWithDatagrok(grok, { service });

@datagrok-libraries/bio is an optional peer dependency — the adapter expects the Datagrok runtime to provide it.

Package entry points

| Import | Contents | | --- | --- | | @datagrok-libraries/hwe | Core: service, parser, renderer, editor, calculations | | @datagrok-libraries/hwe/datagrok | Datagrok adapter | | @datagrok-libraries/hwe/styles.css | Editor stylesheet (interactive UI) |

License

GPL-3.0-only. Bundled third-party components (lru-cache, Lucide icon paths) retain their own licenses — see THIRD-PARTY-NOTICES.txt.