@qe-libs/qeviz 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -205,6 +205,53 @@ The `<qe-visual>` and `<qe-graph>` elements can be used directly in any HTML pag
205
205
  </script>
206
206
  ```
207
207
 
208
+ On [qe-libs.org/npm/qe-libs-qeviz/](https://qe-libs.org/npm/qe-libs-qeviz/)
209
+ the `js run` examples have a **Run** button and draw under the example;
210
+ `demo.show(element)` puts an element there and exists only on that page. This
211
+ one fits an ENA model in the browser with
212
+ [`@qe-libs/rena-wasm`](https://qe-libs.org/npm/qe-libs-rena-wasm/) (WebAssembly)
213
+ on its demo copy of rENA's `RS.data`, and plots it:
214
+
215
+ ```js run
216
+ import '@qe-libs/qeviz'; // defines <qe-visual>, <qe-graph>, ...
217
+ import loadENA from '@qe-libs/rena-wasm';
218
+
219
+ const ena = await loadENA();
220
+ const rows = await demo.csv('@qe-libs/rena-wasm/demo/RS.csv');
221
+ const m = ena.fit(rows, {
222
+ codes: ['Data', 'Technical.Constraints', 'Performance.Parameters',
223
+ 'Client.and.Consultant.Requests', 'Design.Reasoning', 'Collaboration'],
224
+ units: ['Condition', 'UserName'], conversations: ['Condition', 'GroupName'], window: 4,
225
+ });
226
+
227
+ // rena-wasm model → ModelData (as qeviz.from_ena does in Python)
228
+ const frame = data => ({ data, types: Object.fromEntries(Object.entries(data[0])
229
+ .map(([k, v]) => [k, typeof v === 'number' ? 'numeric' : 'character'])) });
230
+ const d = m.dims, nc = m.nConnections, units = m.model.unitLabels;
231
+ const condition = u => u.split('__')[0];
232
+ const cols = m.connectionNames.map(n => n.replace(' & ', '.'));
233
+ const model = {
234
+ nodes: frame(m.rotation.codes.map((code, i) =>
235
+ ({ code, x: m.rotation.nodes[i * d], y: m.rotation.nodes[i * d + 1] }))),
236
+ points: frame(units.map((unit, i) =>
237
+ ({ unit, x: m.points[i * d], y: m.points[i * d + 1], Condition: condition(unit) }))),
238
+ edges: frame(units.map((unit, i) => Object.fromEntries([['unit', unit],
239
+ ...cols.map((c, j) => [c, m.lineWeights[i * nc + j]]), ['Condition', condition(unit)]]))),
240
+ id_col: 'unit', node_id_col: 'code', group_col: 'Condition',
241
+ };
242
+
243
+ const vis = document.createElement('qe-visual');
244
+ vis.innerHTML = `
245
+ <qe-graph width="100%" height="440">
246
+ <qe-nodes label="on"></qe-nodes>
247
+ <qe-means confidence label="on"></qe-means>
248
+ <qe-points></qe-points>
249
+ <qe-edges group="FirstGame" also="SecondGame"></qe-edges>
250
+ <qe-axes x y></qe-axes>
251
+ </qe-graph>`;
252
+ demo.show(vis).setModelData(model);
253
+ ```
254
+
208
255
  By default, all marks (nodes, mean markers, unit dots) size in graph-coordinate
209
256
  units and scale with the data extent and wheel-zoom. Add `fixed-size` to
210
257
  `<qe-points>` or `<qe-means>` to keep those markers a constant on-screen pixel
@@ -321,6 +368,23 @@ vis.setModelData({
321
368
  // <qe-graph><qe-nodes></qe-nodes><qe-edges network="n1"></qe-edges></qe-graph>
322
369
  ```
323
370
 
371
+ Runnable:
372
+
373
+ ```js run
374
+ import '@qe-libs/qeviz';
375
+
376
+ const vis = document.createElement('qe-visual');
377
+ vis.innerHTML = `<qe-graph width="100%" height="320">
378
+ <qe-nodes label="on"></qe-nodes><qe-edges network="n1"></qe-edges></qe-graph>`;
379
+ demo.show(vis).setModelData({
380
+ nodes: { data: [{ code: "A", x: 0.9, y: 0.3 }, { code: "B", x: -0.6, y: 0.8 },
381
+ { code: "C", x: -0.2, y: -0.9 }],
382
+ types: { code: "character" } },
383
+ networks: { data: [{ name: "n1", "A.B": 0.8, "A.C": 0.3, "B.C": -0.5 }],
384
+ types: { name: "character" } },
385
+ });
386
+ ```
387
+
324
388
  With the default `color-scale="model"`, the colour range comes from the `edges`
325
389
  frame when the model has one, and otherwise from every row of `networks`.
326
390
 
@@ -358,6 +422,23 @@ radius (as webENA's sigma plots do), so the self weight only sets its colour;
358
422
  a number is that fraction of the node radius. Without it the dot is sized by
359
423
  its weight.
360
424
 
425
+ Single edges and nodes in their own colour, e.g. to highlight a selection:
426
+
427
+ ```html
428
+ <qe-nodes>
429
+ <qe-node node="Data" color="#EE9621"></qe-node>
430
+ </qe-nodes>
431
+ <qe-edges network="n1">
432
+ <qe-edge source="Data" target="Design" color="#EE9621"></qe-edge>
433
+ </qe-edges>
434
+ ```
435
+
436
+ Only the edges and nodes that differ need a child. A `<qe-edge>` colour is
437
+ drawn exactly as given, in place of the layer's `colors` and weight ramps; in
438
+ an undirected model either order of `source` / `target` matches, in a directed
439
+ one only source → target. A `<qe-node>` colours its node and its label.
440
+ Adding, changing or removing a child redraws the plot.
441
+
361
442
  Pixel sizes (`size`, like `label-font-size`) are converted against the range,
362
443
  so with the default `view-padding` they come out at size ÷ 1.2.
363
444
 
@@ -490,10 +571,57 @@ graph.toSVG(); // standalone SVG string
490
571
  await graph.toPNG(2); // PNG data URL (2× resolution)
491
572
  ```
492
573
 
574
+ ### Static SVG without a browser
575
+
576
+ `renderSVG()` draws the plot a `<qe-graph>` and its layer elements would draw
577
+ for a model, as a standalone SVG string, with no `window`, `document` or
578
+ `customElements`: qeviz brings its own browser-free element tree. It runs in
579
+ Node and Cloudflare Workers (nothing Node-specific is used), so a server, a
580
+ CLI or a language adapter can export the same plot the web component shows,
581
+ without jsdom or a headless browser.
582
+
583
+ ```js
584
+ import { renderSVG } from '@qe-libs/qeviz';
585
+
586
+ const svg = renderSVG(modelData, {
587
+ width: 600, height: 600, // CSS px; default 600 × width
588
+ graph: { 'edge-width': 0.04, 'plot-title': 'FirstGame' }, // <qe-graph> attributes
589
+ layers: [ // child elements, in markup order
590
+ 'qe-nodes',
591
+ ['qe-means', { confidence: true, label: 'on' }],
592
+ ['qe-points', { label: 'auto' }],
593
+ ['qe-edges', { group: 'FirstGame', also: 'SecondGame' }],
594
+ ['qe-axes', { x: true, y: true }],
595
+ ],
596
+ });
597
+ ```
598
+
599
+ A layer is a tag name, or `[tag, attributes]`; an attribute of `true` is a bare
600
+ attribute (`<qe-means confidence>`), `false` / `null` leaves it out, and other
601
+ values are stringified. The result is the same SVG the browser produces for the
602
+ same markup and `setModelData()` call (checked element by element against
603
+ jsdom by `tools/headless-parity/check.mjs`), with the plot's `width` / `height`
604
+ on the root. Pixel-sized settings (`label-font-size`, `fixed-size`, `size`
605
+ columns) are converted at the given `width`.
606
+
607
+ Two things a browser does that a headless render cannot: measure text, and
608
+ animate. Label boxes are estimated from the font size and text length (an
609
+ average sans-serif glyph is 0.6 em wide), so a label that a browser nudges
610
+ inside the plot is nudged by that estimate instead. `animate`, events,
611
+ tooltips and zoom / pan do not exist headless; the output is the final frame at
612
+ zoom 1.
613
+
614
+ `renderHeadless(modelData, options)` returns the (unconnected) `<qe-graph>`
615
+ element itself instead of the string, for the resolved plot data (`getNodes()`,
616
+ `getEdges()`, `getPoints()`) or `toSVG()`. In a browser, use the element and
617
+ `toSVG()` instead; `renderSVG` is for environments without a DOM.
618
+
493
619
  ### Selection / highlight
494
620
 
495
621
  Drive selection styling from the host without touching qeviz's internal DOM. The
496
- highlight is an overlay that survives model updates and follows zoom and pan:
622
+ highlight is an overlay (rings and a glow line) that survives model updates and
623
+ follows zoom and pan; to colour the marks themselves instead, use `<qe-edge>` /
624
+ `<qe-node>` children (above):
497
625
 
498
626
  ```js
499
627
  graph.setHighlight({ edges: [{ source: "Data", target: "Design" }], nodes: ["Data"] });