@glossarist/concept-browser 0.7.90 → 0.7.91

package/src/components/relation-sphere/forces.ts

@@ -0,0 +1,156 @@
+/**
+ * d3-force-compatible force factories for the sphere simulation.
+ *
+ * Extracted from RelationSphere.vue. Each factory is pure — takes a
+ * ForcesContext (read-only getters for the mutable sim state) and
+ * returns a Force compatible with d3-force-simulation's `.force()`.
+ *
+ * Forces in play:
+ *   - sphereConstraint: renormalizes node positions to the unit sphere
+ *     each tick (‖p‖ = 1) and projects velocity onto the tangent plane.
+ *   - velocityClamp(maxV): caps ‖v‖ at maxV to prevent runaway sim.
+ *   - repulsion: pairwise chord-distance repulsion so cards spread on
+ *     the sphere surface. Focus (depth=0) is immovable.
+ *   - linkForce: 3D spring pulling connected nodes toward a target
+ *     chord distance. Skips muted types / muted registers.
+ *   - focusPin: pins the focus node at (0, 0, 1).
+ *
+ * navForce stays inline in RelationSphere.vue — its state
+ * (navActive/navStart/navEnd/etc.) has 10+ touch points in the Vue
+ * component's navigation logic, so extracting it adds risk without
+ * proportional benefit.
+ */
+import type { Force, ForcesContext, SNode } from './types';
+
+/** Renormalize ‖p‖ = 1 each tick + project velocity onto tangent plane. */
+export function sphereConstraint(): Force {
+  let nL: SNode[] = [];
+  const force = () => {
+    for (const n of nL) {
+      const len = Math.sqrt(n.x * n.x + n.y * n.y + n.z * n.z);
+      if (len > 0.001) {
+        const nx = n.x / len, ny = n.y / len, nz = n.z / len;
+        n.x = nx; n.y = ny; n.z = nz;
+        const rad = n.vx * nx + n.vy * ny + n.vz * nz;
+        n.vx -= rad * nx; n.vy -= rad * ny; n.vz -= rad * nz;
+      }
+    }
+  };
+  (force as Force).initialize = (n: SNode[]) => { nL = n; };
+  return force as Force;
+}
+
+/** Cap ‖v‖ at maxV to prevent runaway simulation. */
+export function velocityClamp(maxV: number): Force {
+  let nL: SNode[] = [];
+  const force = () => {
+    for (const n of nL) {
+      const v2 = n.vx * n.vx + n.vy * n.vy + n.vz * n.vz;
+      if (v2 > maxV * maxV) {
+        const s = maxV / Math.sqrt(v2);
+        n.vx *= s; n.vy *= s; n.vz *= s;
+      }
+    }
+  };
+  (force as Force).initialize = (n: SNode[]) => { nL = n; };
+  return force as Force;
+}
+
+/**
+ * Pairwise repulsion — pushes nodes apart on the sphere surface so
+ * cards don't stack. Operates in 3D (chord distance), with the
+ * sphereConstraint normalizing positions back to the unit sphere
+ * each tick. Focus node (depth=0) is immovable.
+ */
+export function repulsion(ctx: ForcesContext): Force {
+  let nL: SNode[] = [];
+  const force = () => {
+    const minDist = ctx.repulseMinDist();
+    const strength = ctx.repulseStrength();
+    const min2 = minDist * minDist;
+    for (let i = 0; i < nL.length; i++) {
+      const a = nL[i];
+      if (a.depth === 0) continue;  /* focus pinned */
+      for (let j = i + 1; j < nL.length; j++) {
+        const b = nL[j];
+        const dx = a.x - b.x, dy = a.y - b.y, dz = a.z - b.z;
+        const d2 = dx * dx + dy * dy + dz * dz;
+        if (d2 >= min2 || d2 < 1e-6) continue;
+        const d = Math.sqrt(d2);
+        const f = (strength * (minDist - d)) / d;
+        const fx = dx * f, fy = dy * f, fz = dz * f;
+        a.vx += fx; a.vy += fy; a.vz += fz;
+        if (b.depth !== 0) { b.vx -= fx; b.vy -= fy; b.vz -= fz; }
+      }
+    }
+  };
+  (force as Force).initialize = (n: SNode[]) => { nL = n; };
+  return force as Force;
+}
+
+/**
+ * 3D spring (link) force — pulls connected nodes toward a target chord
+ * distance. This is what actually spreads cards apart: longer springs
+ * (higher Expand level) push the graph outward along its edges. Stock
+ * d3-forceLink only handles x/y; this custom version operates in full
+ * 3D so the sphereConstraint can renormalize positions correctly.
+ *
+ * Skips edges involving muted types or muted registers (except when
+ * the focus node is on either end).
+ */
+export function linkForce(ctx: ForcesContext): Force {
+  let nL: SNode[] = [];
+  let idToIdx = new Map<string, number>();
+  const force = () => {
+    const links = ctx.links();
+    if (links.length === 0) return;
+    const target = ctx.linkDistance();
+    const strength = ctx.linkStrength();
+    /* Read muted sets each tick so toggleType/toggleRegister take effect
+       immediately on the next simulation step. */
+    const mutedT = ctx.mutedTypes();
+    const mutedR = ctx.mutedRegisters();
+    for (const link of links) {
+      if (mutedT.has(link.type)) continue;
+      const ai = idToIdx.get(link.source);
+      const bi = idToIdx.get(link.target);
+      if (ai === undefined || bi === undefined) continue;
+      const a = nL[ai], b = nL[bi];
+      /* Skip edges involving a muted register (unless the node is the focus) */
+      if (a.depth !== 0 && mutedR.has(a.register)) continue;
+      if (b.depth !== 0 && mutedR.has(b.register)) continue;
+      const dx = b.x - a.x, dy = b.y - a.y, dz = b.z - a.z;
+      const d2 = dx * dx + dy * dy + dz * dz;
+      if (d2 < 1e-6) continue;
+      const d = Math.sqrt(d2);
+      const diff = ((d - target) / d) * strength;
+      const fx = dx * diff, fy = dy * diff, fz = dz * diff;
+      if (a.depth !== 0) { a.vx += fx; a.vy += fy; a.vz += fz; }
+      if (b.depth !== 0) { b.vx -= fx; b.vy -= fy; b.vz -= fz; }
+    }
+  };
+  (force as Force).initialize = (n: SNode[]) => {
+    nL = n;
+    idToIdx = new Map();
+    for (let i = 0; i < n.length; i++) idToIdx.set(n[i].id, i);
+  };
+  return force as Force;
+}
+
+/**
+ * Pin the focus node at (0, 0, 1) so neighbor repulsion doesn't shove
+ * it. Without this, the focus drifts and the whole sphere wobbles.
+ */
+export function focusPin(): Force {
+  let nL: SNode[] = [];
+  const force = () => {
+    for (const n of nL) {
+      if (n.depth === 0) {
+        n.x = 0; n.y = 0; n.z = 1;
+        n.vx = 0; n.vy = 0; n.vz = 0;
+      }
+    }
+  };
+  (force as Force).initialize = (n: SNode[]) => { nL = n; };
+  return force as Force;
+}

package/src/components/relation-sphere/rake-bundles.ts

@@ -0,0 +1,221 @@
+/**
+ * Rake bundle rendering for the RelationSphere.
+ *
+ * Draws ISO 704:2022 partitive-relation rakes (right-angle "fork"
+ * notation) on the SVG layer. Each relation becomes:
+ *
+ *      comprehensive
+ *          │  (stem, frame-width solid)
+ *          ◆──────────────  (spine, frame-width solid)
+ *          │       │
+ *          │       │  (drop, per-member multiplicity + delimiting)
+ *          ▼       ▼
+ *        partitive partitive
+ *
+ * Per-member drop style derives from presence × count × is_delimiting
+ * via rakeStrokeStyle() — solid/dashed lines, 1 or 2 lines, normal or
+ * 3× delimiting width.
+ *
+ * Extracted from RelationSphere.vue (1914 lines → smaller). Pure
+ * DOM/geometry — no Vue reactivity, no d3 state. The caller passes
+ * the partitive relations, position map, and rendering context.
+ */
+import type { PartitiveRelationWire, PartitiveMemberWire } from '../../adapters/types';
+import type { RakeStrokeStyle } from '../../utils/partitive-multiplicity';
+import { rakeStrokeStyle } from '../../utils/partitive-multiplicity';
+import { UriRouter } from '../../adapters/UriRouter';
+
+const DOUBLE_GAP = 4;
+const DASH = '4 3';
+const FRAME_STROKE_WIDTH = 1.4;
+const SPINE_FRACTION = 0.55;
+const PARTIAL_TAIL = 28;
+
+export interface RakeBundleOptions {
+  /** Light/dark mode controls the frame contrast color. */
+  isDark: boolean;
+  /** Relation color (light or dark variant of the partitive teal). */
+  color: string;
+  /** Skip the entire bundle when the user mutes partitive relations. */
+  isMuted: boolean;
+  /** Relations to draw. */
+  relations: readonly PartitiveRelationWire[];
+}
+
+interface NodePos { x: number; y: number; }
+
+interface Tooth {
+  member: PartitiveMemberWire;
+  partitivePos: NodePos;
+  toothX: number;
+  toothY: number;
+  along: number;
+  style: RakeStrokeStyle;
+}
+
+/**
+ * Draw all rake bundles for the current concept's partitive relations.
+ *
+ * Each relation produces: 1 stem, 1 spine, 1–2 drops per member,
+ * 1 junction circle at the spine center, 1 diamond at the comp end.
+ */
+export function drawRakeBundles(
+  svg: SVGSVGElement,
+  pos: Map<string, NodePos>,
+  opts: RakeBundleOptions,
+): void {
+  if (opts.isMuted) return;
+  const contrastStroke = opts.isDark ? '#0a1f1c' : '#ffffff';
+
+  for (const rel of opts.relations) {
+    const compParsed = UriRouter.parseUri(rel.comprehensive);
+    if (!compParsed) continue;
+    const compNodeId = `${compParsed.registerId}/${compParsed.conceptId}`;
+    const compPos = pos.get(compNodeId);
+    if (!compPos) continue;
+
+    const memberPositions = rel.partitives
+      .map(member => {
+        const parsed = UriRouter.parseUri(member.uri);
+        if (!parsed) return null;
+        const nid = `${parsed.registerId}/${parsed.conceptId}`;
+        const p = pos.get(nid);
+        return p ? { member, pos: p } : null;
+      })
+      .filter((x): x is { member: PartitiveMemberWire; pos: NodePos } => x !== null);
+
+    if (memberPositions.length === 0) continue;
+
+    // 1. Compute stem-axis (comp → centroid of partitives) and spine-axis (perpendicular)
+    const centroidX = memberPositions.reduce((s, m) => s + m.pos.x, 0) / memberPositions.length;
+    const centroidY = memberPositions.reduce((s, m) => s + m.pos.y, 0) / memberPositions.length;
+    const stemDx = centroidX - compPos.x;
+    const stemDy = centroidY - compPos.y;
+    const stemLen = Math.hypot(stemDx, stemDy) || 1;
+    const stemDirX = stemDx / stemLen;
+    const stemDirY = stemDy / stemLen;
+    const spineDirX = -stemDirY;
+    const spineDirY = stemDirX;
+
+    // 2. Spine center: along stem-axis at SPINE_FRACTION from comp
+    const spineCx = compPos.x + stemDirX * stemLen * SPINE_FRACTION;
+    const spineCy = compPos.y + stemDirY * stemLen * SPINE_FRACTION;
+
+    // 3. Tooth positions = projection of each partitive onto spine line
+    const teeth: Tooth[] = memberPositions.map(({ member, pos: pPos }) => {
+      const vx = pPos.x - spineCx;
+      const vy = pPos.y - spineCy;
+      const along = vx * spineDirX + vy * spineDirY;
+      const toothX = spineCx + spineDirX * along;
+      const toothY = spineCy + spineDirY * along;
+      return {
+        member,
+        partitivePos: pPos,
+        toothX,
+        toothY,
+        along,
+        style: rakeStrokeStyle(member.presence, member.count, member.isDelimiting),
+      };
+    });
+
+    // 4. Spine extents (leftmost to rightmost tooth along spine-axis)
+    let minAlong = teeth[0].along;
+    let maxAlong = teeth[0].along;
+    for (const t of teeth) {
+      if (t.along < minAlong) minAlong = t.along;
+      if (t.along > maxAlong) maxAlong = t.along;
+    }
+    // For completeness: 'partial', extend past last tooth (continued backline)
+    if (rel.completeness === 'partial') maxAlong += PARTIAL_TAIL;
+    const spineStartX = spineCx + spineDirX * minAlong;
+    const spineStartY = spineCy + spineDirY * minAlong;
+    const spineEndX = spineCx + spineDirX * maxAlong;
+    const spineEndY = spineCy + spineDirY * maxAlong;
+
+    // 5. Stem: comp → spine center (frame — single solid)
+    drawSegment(svg, opts.color, compPos.x, compPos.y, spineCx, spineCy, { width: FRAME_STROKE_WIDTH });
+
+    // 6. Spine: leftmost tooth → rightmost tooth (frame — single solid)
+    if (Math.abs(maxAlong - minAlong) > 1) {
+      drawSegment(svg, opts.color, spineStartX, spineStartY, spineEndX, spineEndY, { width: FRAME_STROKE_WIDTH });
+    }
+
+    // 7. Drops: tooth → partitive (per-member multiplicity + delimiting).
+    //    1 or 2 parallel lines per the style.
+    for (const tooth of teeth) {
+      drawSegment(svg, opts.color, tooth.toothX, tooth.toothY, tooth.partitivePos.x, tooth.partitivePos.y, {
+        width: tooth.style.strokeWidth,
+        dashed: tooth.style.primaryDashed,
+      });
+      if (tooth.style.lineCount === 2) {
+        drawSegment(svg, opts.color, tooth.toothX, tooth.toothY, tooth.partitivePos.x, tooth.partitivePos.y, {
+          width: tooth.style.strokeWidth,
+          dashed: tooth.style.secondaryDashed,
+          offset: DOUBLE_GAP,
+        });
+      }
+    }
+
+    // 8. Junction marker at spine center (the right-angle corner)
+    const junction = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
+    junction.setAttribute('class', 'rake-junction');
+    junction.setAttribute('cx', String(spineCx));
+    junction.setAttribute('cy', String(spineCy));
+    junction.setAttribute('r', '2.5');
+    junction.setAttribute('fill', opts.color);
+    junction.setAttribute('opacity', '0.9');
+    junction.setAttribute('stroke', contrastStroke);
+    junction.setAttribute('stroke-width', '1');
+    svg.appendChild(junction);
+
+    // 9. Diamond marker at comprehensive end (hyperedge origin)
+    const diamond = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    const dsize = 5;
+    diamond.setAttribute('d',
+      `M ${compPos.x} ${compPos.y - dsize} L ${compPos.x + dsize} ${compPos.y} L ${compPos.x} ${compPos.y + dsize} L ${compPos.x - dsize} ${compPos.y} Z`);
+    diamond.setAttribute('fill', opts.color);
+    diamond.setAttribute('opacity', '0.9');
+    diamond.setAttribute('stroke', contrastStroke);
+    diamond.setAttribute('stroke-width', '1');
+    svg.appendChild(diamond);
+  }
+}
+
+interface SegmentOpts {
+  width: number;
+  dashed?: boolean;
+  offset?: number;
+  opacity?: number;
+}
+
+/**
+ * Draw a single straight segment with the given style.
+ *
+ * Stem + spine use FRAME_STROKE_WIDTH (single solid frame).
+ * Drops use the per-member multiplicity + delimiting style.
+ */
+function drawSegment(
+  svg: SVGSVGElement,
+  color: string,
+  ax: number, ay: number, bx: number, by: number,
+  opts: SegmentOpts,
+): void {
+  const opacity = opts.opacity ?? 0.85;
+  const offset = opts.offset ?? 0;
+  const dashed = opts.dashed ?? false;
+  const dx = bx - ax, dy = by - ay;
+  const len = Math.hypot(dx, dy) || 1;
+  const px = -dy / len, py = dx / len;
+  const line = document.createElementNS('http://www.w3.org/2000/svg', 'line');
+  line.setAttribute('class', 'rake-seg');
+  line.setAttribute('x1', String(ax + px * offset));
+  line.setAttribute('y1', String(ay + py * offset));
+  line.setAttribute('x2', String(bx + px * offset));
+  line.setAttribute('y2', String(by + py * offset));
+  line.setAttribute('stroke', color);
+  line.setAttribute('stroke-width', String(opts.width));
+  line.setAttribute('opacity', String(opacity));
+  line.setAttribute('stroke-linecap', 'square');
+  if (dashed) line.setAttribute('stroke-dasharray', DASH);
+  svg.appendChild(line);
+}

package/src/components/relation-sphere/svg-markers.ts

@@ -0,0 +1,52 @@
+/**
+ * SVG marker definitions for the RelationSphere edge rendering.
+ *
+ * Extracted from RelationSphere.vue for scannability. Pure DOM
+ * helpers — no Vue reactivity, no d3 state.
+ */
+
+/**
+ * Ensure the SVG has a `<defs>` element. No-op if one already exists.
+ * Call once per render pass before adding markers.
+ */
+export function ensureMarkers(svg: SVGSVGElement): void {
+  let defs = svg.querySelector('defs');
+  if (!defs) {
+    defs = document.createElementNS('http://www.w3.org/2000/svg', 'defs');
+    svg.appendChild(defs);
+  }
+}
+
+/**
+ * Lazy per-type arrow marker. Arrow color matches the edge's per-type
+ * color (which may differ from the category color via
+ * TYPE_COLOR_OVERRIDE in relation-sphere-styling).
+ *
+ * Returns the marker id so the caller can reference it via
+ * `marker-end="url(#id)"`. Idempotent — repeated calls for the same
+ * (typeId, color) pair return the existing marker.
+ */
+export function ensureTypeMarker(svg: SVGSVGElement, typeId: string, color: string): string {
+  const safeId = typeId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  const markerId = `rel-arrow-t-${safeId}`;
+  if (svg.querySelector(`#${markerId}`)) return markerId;
+  let defs = svg.querySelector('defs');
+  if (!defs) {
+    defs = document.createElementNS('http://www.w3.org/2000/svg', 'defs');
+    svg.appendChild(defs);
+  }
+  const m = document.createElementNS('http://www.w3.org/2000/svg', 'marker');
+  m.setAttribute('id', markerId);
+  m.setAttribute('viewBox', '0 0 8 8');
+  m.setAttribute('refX', '6');
+  m.setAttribute('refY', '4');
+  m.setAttribute('markerWidth', '5');
+  m.setAttribute('markerHeight', '5');
+  m.setAttribute('orient', 'auto');
+  const p = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+  p.setAttribute('d', 'M 0 0 L 6 4 L 0 8 z');
+  p.setAttribute('fill', color);
+  m.appendChild(p);
+  defs.appendChild(m);
+  return markerId;
+}

package/src/components/relation-sphere/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Sphere graph types: SNode + SLink.
+ *
+ * Extracted from RelationSphere.vue so force factories and rendering
+ * helpers in `relation-sphere/` can share the same types without
+ * reaching into the Vue component.
+ */
+
+export interface SNode {
+  id: string;
+  term: string;
+  definition?: string;
+  /** Languages available on this concept. */
+  languages?: string[];
+  ref: string;
+  register: string;
+  conceptId: string;
+  depth: number;
+  x: number; y: number; z: number;
+  vx: number; vy: number; vz: number;
+}
+
+export interface SLink {
+  source: string;
+  target: string;
+  type: string;
+  category: string;
+  depth: number;
+}
+
+/**
+ * Simulation state shared with the force factories.
+ *
+ * The Vue component holds the mutable bindings; the forces read them
+ * via getters each tick so user changes (Expand slider, mute toggles,
+ * navigation target) take effect on the next simulation step.
+ */
+export interface ForcesContext {
+  nodes: () => SNode[];
+  links: () => SLink[];
+  mutedTypes: () => Set<string>;
+  mutedRegisters: () => Set<string>;
+  /** Expand-slider-driven parameters (link distance/strength, repulse min/strength). */
+  linkDistance: () => number;
+  linkStrength: () => number;
+  repulseMinDist: () => number;
+  repulseStrength: () => number;
+}
+
+/** d3-force-compatible force: a callable + initialize hook. */
+export type Force = ((alpha?: number) => void) & { initialize?: (nodes: SNode[]) => void };