@datagrok/helm 3.0.3 → 3.0.5

package/package.json

@@ -1,19 +1,28 @@
 {
   "name": "@datagrok/helm",
   "friendlyName": "Helm",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "author": {
     "name": "Davit Rizhinashvili",
     "email": "drizhinashvili@datagrok.ai"
   },
   "description": "Provides support for HELM notation (importing, detecting, rendering, conversion).",
+  "properties": [
+    {
+      "name": "MonomersPerRow",
+      "description": "Number of monomers per row before a HELM structure wraps to the next line. Counts nucleotides for RNA/DNA.",
+      "propertyType": "int",
+      "defaultValue": "20",
+      "nullable": false
+    }
+  ],
   "sources": [
     "css/helm.css"
   ],
   "dependencies": {
     "@datagrok-libraries/bio": "^6.0.2",
     "@datagrok-libraries/chem-meta": "^1.2.9",
-    "@datagrok-libraries/hwe": "^1.0.2",
+    "@datagrok-libraries/hwe": "^1.0.5",
     "@datagrok-libraries/test": "^1.3.1",
     "@datagrok-libraries/utils": "^4.6.9",
     "cash-dom": "^8.1.1",

package/src/constants.ts

@@ -24,3 +24,15 @@ export const SDF_MONOMER_NAME = 'MonomerName';
 export const enum TAGS {
   cellRendererRenderError = '.cell-renderer.render.error',
 }
+
+/** Names of package properties declared in the `properties` section of `package.json`. */
+export const enum HelmPackagePropertiesNames {
+  MonomersPerRow = 'MonomersPerRow',
+}
+
+/**
+ * Fallback for `MonomersPerRow` when the package property is missing or
+ * unparseable (a package loaded before its settings, an old install). Kept in
+ * step with the `defaultValue` in package.json and with hwe's own default.
+ */
+export const DEFAULT_MONOMERS_PER_ROW = 20;

package/src/package-api.ts

@@ -23,6 +23,14 @@ export namespace funcs {
     return await grok.functions.call('Helm:EditMoleculeCell', { cell });
   }
 
+  /**
+   * @param {DG.Column} col
+   *   semType: Macromolecule
+   */
+  export async function helmPanel(col: DG.Column ): Promise<any> {
+    return await grok.functions.call('Helm:HelmPanel', { col });
+  }
+
   /**
    * Adds editor
    * @param {any} mol

package/src/package-test.ts

@@ -16,6 +16,7 @@ import './tests/helm-helper-tests';
 import './tests/helm-substructure-filter';
 import './tests/helm-activity-cliffs';
 import './tests/to-atomic-level-ui-non-linear';
+import './tests/wrap-width-tests';
 
 export const _package = new DG.Package();
 export {tests};

package/src/package-utils.ts

@@ -12,6 +12,11 @@ import {ISeqHelper} from '@datagrok-libraries/bio/src/utils/seq-helper';
 
 import * as DG from 'datagrok-api/dg';
 
+import {setMonomersPerRow} from '@datagrok-libraries/hwe';
+
+import {HelmPackagePropertiesNames} from './constants';
+import {resolveMonomersPerRow} from './utils/wrap-width';
+
 import {_package} from './package';
 
 // hwe migration (Phase 7): the legacy Dojo / JSDraw2 / HELMWebEditor loader and
@@ -52,6 +57,38 @@ export class HelmPackage extends DG.Package {
 
   private _initialized: boolean = false;
 
+  // -- Wrapping (line-break) width --
+
+  /**
+   * The package-wide default number of monomers per row, from the
+   * `MonomersPerRow` package property (see the `properties` section of
+   * package.json). This is the DEFAULT: the column widget in `helmPanel` can
+   * override it for the session without touching this value.
+   *
+   * Falls back to {@link DEFAULT_MONOMERS_PER_ROW} when settings are not
+   * loaded yet or hold something unparseable.
+   */
+  public get defaultMonomersPerRow(): number {
+    let raw: unknown;
+    try {
+      raw = this.settings?.[HelmPackagePropertiesNames.MonomersPerRow];
+    } catch {
+      // `settings` reaches into the platform; a package instance that is not
+      // registered yet (or the standalone test bundle's copy) has nothing to
+      // reach into. Fall back rather than break every render.
+      raw = undefined;
+    }
+    return resolveMonomersPerRow(raw);
+  }
+
+  /**
+   * Push {@link defaultMonomersPerRow} into hwe's process-wide layout setting,
+   * which every renderer / editor / adapter reads at layout time.
+   */
+  public applyDefaultMonomersPerRow(): void {
+    setMonomersPerRow(this.defaultMonomersPerRow);
+  }
+
   /** Requires Bio initialized (monomer library). */
   completeInit(helmHelper: IHelmHelper, libHelper: IMonomerLibHelper): void {
     this._helmHelper = helmHelper;

package/src/package.g.ts

@@ -25,6 +25,15 @@ export function editMoleculeCell(cell: any) : void {
   PackageFunctions.editMoleculeCell(cell);
 }
 
+//name: HELM Renderer
+//tags: widgets, panel
+//input: column col { semType: Macromolecule; units: helm }
+//output: widget result
+//meta.role: widgets,panel
+export async function helmPanel(col: DG.Column) : Promise<any> {
+  return await PackageFunctions.helmPanel(col);
+}
+
 //name: Edit Helm...
 //description: Adds editor
 //input: semantic_value mol { semType: Macromolecule }

package/src/package.ts

@@ -15,6 +15,7 @@ import {HelmInputBase, IHelmHelper, IHelmInputInitOptions} from '@datagrok-libra
 import {getMonomerLibHelper} from '@datagrok-libraries/bio/src/types/monomer-library';
 
 import {getPropertiesWidget} from './widgets/properties-widget';
+import {getWrapWidthWidget} from './widgets/wrap-width-widget';
 import {HelmGridCellRenderer, HelmGridCellRendererBack} from './utils/helm-grid-cell-renderer';
 import {HelmPackage} from './package-utils';
 import {HelmHelper} from './helm-helper';
@@ -70,6 +71,11 @@ async function initHelmInt(): Promise<void> {
     const libHelper = await getMonomerLibHelper();
     const helmHelper: IHelmHelper = new HelmHelper(seqHelper, _package.logger, rdKitModule);
     _package.completeInit(helmHelper, libHelper);
+    // Seed hwe's process-wide row-wrap width from the `MonomersPerRow` package
+    // property. Must run before the first cell renders; the column widget in
+    // `helmPanel` can then override it for the session without changing this
+    // default.
+    _package.applyDefaultMonomersPerRow();
   } catch (err: any) {
     const [errMsg, errStack] = errInfo(err);
     grok.shell.error(`Package \'Helm\' init error:\n${errMsg}`);
@@ -151,6 +157,20 @@ export class PackageFunctions {
     checkMonomersAndOpenWebEditor(cell, undefined, undefined);
   }
 
+  @grok.decorators.panel({
+    name: 'HELM Renderer',
+    meta: {role: 'widgets'},
+    tags: ['widgets', 'panel'],
+  })
+  static async helmPanel(
+    @grok.decorators.param({'options': {'semType': 'Macromolecule', 'units': 'helm'}}) col: DG.Column): Promise<DG.Widget> {
+    if (col.meta.units !== NOTATION.HELM)
+      return new DG.Widget(ui.divText('These settings apply only to HELM columns'));
+    // Session-scoped row-wrap width. The package-wide default lives in the
+    // `MonomersPerRow` package property and is not touched here.
+    return getWrapWidthWidget();
+  }
+
 
   @grok.decorators.func({
     'meta': {'action': 'Edit Helm...'},

package/src/tests/wrap-width-tests.ts

@@ -0,0 +1,132 @@
+import * as DG from 'datagrok-api/dg';
+
+import {after, before, category, expect, test} from '@datagrok-libraries/test/src/test';
+import {getWrapSettings, setMonomersPerRow} from '@datagrok-libraries/hwe';
+
+import {initHelmMainPackage} from './utils';
+import {getWrapWidthWidget} from '../widgets/wrap-width-widget';
+import {resolveMonomersPerRow} from '../utils/wrap-width';
+import {DEFAULT_MONOMERS_PER_ROW} from '../constants';
+
+// The int input inside the widget produced by `getWrapWidthWidget`.
+function widgetInput(widget: DG.Widget): HTMLInputElement {
+  const input = widget.root.querySelector('input') as HTMLInputElement | null;
+  if (input === null) throw new Error('wrap-width widget: no input element');
+  return input;
+}
+
+// Set the input the way a user would, so the widget's change handler runs.
+function typeValue(input: HTMLInputElement, value: number): void {
+  input.value = String(value);
+  input.dispatchEvent(new Event('input', {bubbles: true}));
+  input.dispatchEvent(new Event('change', {bubbles: true}));
+}
+
+category('WrapWidth: package property', () => {
+  test('reads an int property', async () => {
+    expect(resolveMonomersPerRow(30), 30);
+  });
+
+  test('reads a string defaultValue straight from package.json', async () => {
+    // An `int` property that has not round-tripped through the server arrives
+    // as the string written in package.json.
+    expect(resolveMonomersPerRow('30'), 30);
+    expect(resolveMonomersPerRow('20'), 20);
+  });
+
+  test('falls back when settings are missing or unusable', async () => {
+    // A NaN reaching the layout would produce a drawing with no coordinates,
+    // so every unusable value must land on the default instead.
+    for (const raw of [undefined, null, '', 'abc', Number.NaN, 0, -5, {}])
+      expect(resolveMonomersPerRow(raw), DEFAULT_MONOMERS_PER_ROW);
+  });
+
+  test('default matches the value declared in package.json', async () => {
+    expect(DEFAULT_MONOMERS_PER_ROW, 20);
+  });
+});
+
+category('WrapWidth: session widget', () => {
+  // The wrap width is process-wide state inside hwe; put it back afterwards so
+  // a failure here cannot change how the rest of the suite renders.
+  let restore: number;
+
+  before(async () => {
+    await initHelmMainPackage();
+    restore = getWrapSettings().monomersPerRow;
+  });
+
+  after(async () => {
+    setMonomersPerRow(restore);
+  });
+
+  test('opens showing the current session value', async () => {
+    setMonomersPerRow(14);
+    const widget = getWrapWidthWidget();
+    try {
+      expect(Number(widgetInput(widget).value), 14);
+    } finally {
+      widget.detach();
+    }
+  });
+
+  test('editing the input changes the session value', async () => {
+    setMonomersPerRow(DEFAULT_MONOMERS_PER_ROW);
+    const widget = getWrapWidthWidget();
+    try {
+      typeValue(widgetInput(widget), 8);
+      expect(getWrapSettings().monomersPerRow, 8);
+    } finally {
+      widget.detach();
+    }
+  });
+
+  test('editing does NOT change the package default', async () => {
+    // This is the whole point of the split: the package property stays the
+    // value every new session starts from.
+    const widget = getWrapWidthWidget();
+    try {
+      typeValue(widgetInput(widget), 5);
+      expect(getWrapSettings().monomersPerRow, 5);
+      expect(resolveMonomersPerRow('20'), 20);
+      expect(DEFAULT_MONOMERS_PER_ROW, 20);
+    } finally {
+      widget.detach();
+    }
+  });
+
+  test('reflects a change made elsewhere', async () => {
+    const widget = getWrapWidthWidget();
+    try {
+      setMonomersPerRow(13);
+      expect(Number(widgetInput(widget).value), 13);
+    } finally {
+      widget.detach();
+    }
+  });
+
+  test('stops tracking after detach', async () => {
+    const widget = getWrapWidthWidget();
+    const input = widgetInput(widget);
+    typeValue(input, 9);
+    widget.detach();
+    setMonomersPerRow(17);
+    // The subscription goes through `widget.sub`, so `detach` unsubscribes it.
+    expect(Number(input.value), 9);
+    expect(getWrapSettings().monomersPerRow, 17);
+  });
+
+  test('a rejected value leaves the session value alone', async () => {
+    setMonomersPerRow(11);
+    const widget = getWrapWidthWidget();
+    try {
+      const input = widgetInput(widget);
+      input.value = '';
+      input.dispatchEvent(new Event('input', {bubbles: true}));
+      input.dispatchEvent(new Event('change', {bubbles: true}));
+      expect(getWrapSettings().monomersPerRow, 11);
+    } finally {
+      widget.detach();
+    }
+  });
+});

package/src/utils/wrap-width.ts

@@ -0,0 +1,18 @@
+import {DEFAULT_MONOMERS_PER_ROW} from '../constants';
+
+/**
+ * Read the `MonomersPerRow` package property into a usable row width.
+ *
+ * Datagrok hands an `int` property back as a number once it has round-tripped
+ * through the server, but a `defaultValue` straight out of package.json arrives
+ * as the string written there, and a package whose settings have not loaded yet
+ * gives `undefined`. All three have to end up at a sane integer — a `NaN` here
+ * would reach the layout and produce a drawing with no coordinates.
+ *
+ * @param {unknown} raw The raw property value.
+ * @return {number} A row width of at least 1, or {@link DEFAULT_MONOMERS_PER_ROW}.
+ */
+export function resolveMonomersPerRow(raw: unknown): number {
+  const parsed = typeof raw === 'number' ? raw : Number.parseInt(String(raw ?? ''), 10);
+  return Number.isFinite(parsed) && parsed >= 1 ? Math.round(parsed) : DEFAULT_MONOMERS_PER_ROW;
+}

package/src/widgets/wrap-width-widget.ts

@@ -0,0 +1,73 @@
+import * as grok from 'datagrok-api/grok';
+import * as ui from 'datagrok-api/ui';
+import * as DG from 'datagrok-api/dg';
+
+import {Subscription} from 'rxjs';
+
+// The wrapping width is a process-wide setting inside hwe, read at layout time
+// by every HelmService / editor / adapter (see @datagrok-libraries/hwe API.md
+// §4.3). That is what lets one input here change both the grid cells and the
+// editor without hunting down the several service instances the package owns.
+import {getWrapSettings, setMonomersPerRow, onWrapSettingsChanged} from '@datagrok-libraries/hwe';
+
+import {_package} from '../package';
+
+/** Widest row the input allows. Well past any readable structure. */
+const MAX_MONOMERS_PER_ROW = 100;
+
+/** Repaint every open grid so HELM cells re-render at the new width. */
+function invalidateHelmGrids(): void {
+  // hwe's own layout / render caches key on a setting version and have already
+  // missed by the time we get here, so a plain repaint is enough.
+  for (const view of grok.shell.tableViews) {
+    try {
+      view.grid?.invalidate();
+    } catch (_err) {
+      // A view can be closing while we iterate; a failed repaint is not worth
+      // failing the whole widget over.
+    }
+  }
+}
+
+/**
+ * Session-scoped control over where HELM structures break into a new line.
+ *
+ * Deliberately does NOT write the package property: the `MonomersPerRow`
+ * package setting stays the default that every session starts from, and this
+ * widget adjusts the current session only. "Reset" puts the session back onto
+ * that default rather than clearing it.
+ *
+ * @return {DG.Widget} The row-width editor.
+ */
+export function getWrapWidthWidget(): DG.Widget {
+  const input = ui.input.int('Monomers per row', {
+    value: getWrapSettings().monomersPerRow,
+    min: 1,
+    max: MAX_MONOMERS_PER_ROW,
+    tooltipText: 'Number of monomers drawn per row before the structure wraps. ' +
+      'Counts nucleotides for RNA/DNA. Applies to this session only. The default comes from the Helm package property',
+    onValueChanged: (value: number | null) => {
+      if (value === null || !Number.isFinite(value)) return;
+      setMonomersPerRow(value);
+      invalidateHelmGrids();
+    },
+  });
+
+  const packageDefault = _package.defaultMonomersPerRow;
+  const resetLink = ui.link('Reset to package default', () => {
+    setMonomersPerRow(packageDefault);
+    invalidateHelmGrids();
+  }, `Back to ${packageDefault} — the MonomersPerRow package property`, {style: {marginTop: '4px'}});
+
+  const widget = new DG.Widget(ui.divV([input.root, resetLink]));
+
+  // Keep the input honest if the setting is changed from anywhere else (the
+  // editor, another widget, a script). `setMonomersPerRow` clamps and rounds,
+  // so this is also how the input reflects a value it did not produce itself.
+  const off = onWrapSettingsChanged((settings) => {
+    if (input.value !== settings.monomersPerRow) input.value = settings.monomersPerRow;
+  });
+  widget.sub(new Subscription(off));
+
+  return widget;
+}