@qe-libs/qeviz 0.2.0 → 0.5.1

package/README.md

@@ -129,17 +129,21 @@ All three languages share the same chain operations:
 | `compare` | Second group to subtract (`group − compare`). Positive differences use the primary colour. |
 | `also` | Second group to overlay alongside `group`. |
 | `show` / `show=false` | Suppress all edges. |
+| `color_scale` | Colour mapping (webENA ramps: saturation 0.25–1, opacity 0.3–1). `"model"` (default) rescales across the whole model, so plots of one model share a colour scale; `"plot"` rescales within the plot (webENA); `"absolute"` uses saturation = opacity = weight. |
+| `edge_width` | Width of a weight-1 edge as a fraction of the plot width (default 0.04). Width is absolute — equal weights draw equally wide — and each node's diameter is the sum of its edges' widths. |
+| `magnify` | Multiply this plot's widths and node sizes (not colour), e.g. for a faint subtraction. When set (even `1`), the plot is labelled "(scaled N.Nx)". |
 
 Label modes: `"on"`, `"off"`, `"click"`, `"auto"`.
 
 ### `qe_axes` / `.axes()` parameters
 
 Axes are **opt-in**: a plot draws the x/y axis cross only when `qe_axes()` is in the
-chain (or a `<qe-axes>` element is present). Each axis label is controlled independently:
+chain (or a `<qe-axes>` element is present). Axis labels are opt-in too: `qe_axes()` alone
+draws the lines with no labels. Each label is controlled independently:
 
 | Parameter | Description |
 |---|---|
-| `x` | `TRUE` labels the x-axis with its dimension name, a string sets custom text, `FALSE` omits the x-axis label. |
+| `x` | `FALSE` (default) omits the x-axis label, `TRUE` labels it with its dimension name (e.g. `SVD1`), a string sets custom text. |
 | `y` | Same as `x`, for the y-axis. |
 | `show` / `show=false` | Suppress the axes entirely. |
 
@@ -149,7 +153,7 @@ qe_plot(set) |> qe_edges("FirstGame") |> qe_axes(x = "Task focus", y = TRUE)
 
 ## TypeScript / web component
 
-The `<qe-visual>` and `<qe-graph>` elements can be used directly in any HTML page.  Layer configuration uses declarative child elements:
+The `<qe-visual>` and `<qe-graph>` elements can be used directly in any HTML page. Mark sizes and colour follow webENA: `<qe-graph edge-width>` sets the width of a weight-1 edge (absolute, as a fraction of the plot width), `<qe-edges color-scale>` picks the colour rescaling (`model` / `plot` / `absolute`), and `<qe-edges magnify>` scales one plot and labels it.  Layer configuration uses declarative child elements; each layer draws only when its element is present. Code-node positions always come from the model and set the plot extent, but the nodes are drawn only when `<qe-nodes>` is present. The R / Python / Julia wrappers emit `<qe-nodes>` alongside an edge network by default (`qe_nodes()` / `.nodes()` override that).
 
 ```html
 <script src="qeviz.umd.js"></script>
@@ -160,6 +164,7 @@ The `<qe-visual>` and `<qe-graph>` elements can be used directly in any HTML pag
     <qe-means confidence label="on"></qe-means>
     <qe-points label="auto"></qe-points>
     <qe-edges group="FirstGame" also="SecondGame"></qe-edges>
+    <qe-axes x y></qe-axes>
   </qe-graph>
 </qe-visual>
 
@@ -168,6 +173,46 @@ The `<qe-visual>` and `<qe-graph>` elements can be used directly in any HTML pag
 </script>
 ```
 
+By default, all marks (nodes, mean markers, unit dots) size in graph-coordinate
+units and scale with the data extent and wheel-zoom. Add `fixed-size` to
+`<qe-points>` or `<qe-means>` to keep those markers a constant on-screen pixel
+size instead — useful when embedding coordinated plots at different scales (the
+webENA use case):
+
+```html
+<qe-points fixed-size></qe-points>
+<qe-means fixed-size></qe-means>
+```
+
+In the language adapters this is `fixed_size = TRUE` on `qe_points()` / `qe_group()`
+(R), `fixed_size=True` on `.points()` / `.group()` (Python), and
+`fixed_size=true` on `qe_points` / `qe_group` (Julia).
+
+#### Point scaling and centring
+
+Unit points and means sit much closer to the origin than the code nodes, so
+by default qeviz rescales them to fill the plot. Two `<qe-graph>` attributes
+change how points are scaled and where the view is centred; both are optional
+and unset by default:
+
+| `<qe-graph>` attributes | Points are multiplied by |
+|---|---|
+| neither (default) | qeviz's fit: farthest node ÷ farthest point, so the outermost point meets the outermost node (the ENA Web Tool's default) |
+| `scale-points="false"` | 1: raw coordinates, where each point sits at its network's centroid |
+| `point-scale="N"` | N, overriding both, e.g. to match another tool's scaling |
+
+`center="content"` centres the view on the middle of the nodes' and points'
+bounding box instead of the origin (0, 0), so a network that sits off to one
+side of the origin fills the plot; `range="network"` is then measured from that
+centre. The default is the origin, the ENA convention.
+
+```html
+<qe-graph scale-points="false" center="content"></qe-graph>
+```
+
+In R these are `qe_plot(scale_points =, point_scale =, center =)`; the Python and
+Julia adapters set them as `<qe-graph>` attributes for now.
+
 Child element presence controls layer visibility — add `<qe-points>` to show unit dots, omit it to hide them.  A `MutationObserver` watches for child additions, removals, and attribute changes, so interactive controls can manipulate the DOM directly:
 
 ```js
@@ -177,6 +222,93 @@ edges.setAttribute("compare", "SecondGame");
 edges.removeAttribute("also");
 ```
 
+### Events
+
+`<qe-graph>` dispatches interaction events on the public element with
+`bubbles: true, composed: true`, so a host app can subscribe regardless of shadow
+DOM. Each event's `detail` also carries the `originalEvent`.
+
+| Event | `detail` |
+|---|---|
+| `qe-edge-click` / `qe-edge-hover` / `qe-edge-unhover` | `{ source, target, weight, directed, self, group?, unit? }` |
+| `qe-node-click` / `qe-node-hover` / `qe-node-unhover` | `{ id, kind: "node" \| "mean" \| "point", name, x, y, group?, unit? }` |
+| `qe-label-move` | `{ id, transform: { x, y } }` — a label was dragged (offset in graph-space units) |
+
+Labels are **draggable** (drag to reposition; the label pins open and stays
+visible), emitting `qe-label-move` on drop so the host can persist the position
+or mirror it across coordinated plots.
+
+For a quick built-in tooltip on hover — `source – target (weight)` over edges,
+the mark name over nodes — add the `tooltip` attribute to `<qe-graph>`. It is
+opt-in; most hosts render their own from the hover events instead.
+
+```html
+<qe-graph tooltip>…</qe-graph>
+```
+
+`source`/`target` are code-node names; `x`/`y` are graph-space coordinates. Unhover
+events carry `{ key }` identifying the mark/edge that was left. The host reacts and
+pushes state back declaratively (ModelData + layer attributes) — qeviz adds no
+framework coupling.
+
+```js
+graph.addEventListener("qe-edge-click", (e) => {
+  const { source, target, weight } = e.detail;   // e.g. open a conversation view
+});
+graph.addEventListener("qe-node-click", (e) => {
+  if (e.detail.kind === "point") plotUnit(e.detail.id);
+});
+```
+
+### Instance access & read APIs
+
+Give coordinated plots an identity and look them up, and read the resolved model
+for host-side hit-testing or export:
+
+```js
+import { getGraph, getGraphs } from "@qe-libs/qeviz";
+
+getGraph("comparison");            // by id or plot-group attribute
+getGraphs();                       // all connected <qe-graph> instances
+
+const graph = getGraph("comparison");
+graph.getNodes();                  // [{ id, name, x, y }, …]
+graph.getEdges();                  // [{ source, target, weight, directed, self }, …]
+graph.getPoints();                 // [{ id, group, x, y }, …] (unit points)
+graph.pointsInRect({ x, y, w, h }); // ids of unit points in a graph-space rect
+```
+
+### Transitions & export
+
+Opt into animated transitions with the `animate` attribute — on the next
+`setModelData`, marks glide from their old positions to the new ones instead of
+snapping (default 300 ms; `animate="500"` sets the duration):
+
+```html
+<qe-graph animate>…</qe-graph>
+```
+
+Snapshot the current plot for download or embedding:
+
+```js
+graph.toSVG();          // standalone SVG string
+await graph.toPNG(2);   // PNG data URL (2× resolution)
+```
+
+### Selection / highlight
+
+Drive selection styling from the host without touching qeviz's internal DOM. The
+highlight is an overlay that survives model updates:
+
+```js
+graph.setHighlight({ edges: [{ source: "Data", target: "Design" }], nodes: ["Data"] });
+graph.clearHighlight();
+```
+
+```html
+<qe-graph id="primary" plot-group="comparison" …></qe-graph>
+```
+
 ### Build
 
 ```sh