@reddb-io/ui 0.1.1 → 0.3.0

package/src/lib/renderers/graph-sigma.ts

@@ -54,6 +54,24 @@ export function sigmaNodeSize(type: string, incomingScale: number): number {
   return nodeVisualRadius(type, incomingScale) * SIGMA_SIZE_FACTOR;
 }
 
+// ─── community supernode sizing (collapsed-cluster rendering) ───────────────
+
+/** Light stroke that marks a supernode as an expandable cluster. */
+export const SUPERNODE_STROKE_COLOR = "#e2e8f0";
+
+/**
+ * Supernode radius in the SVG fallback's [0, 100] space — grows with the
+ * member count (sub-linear so a 500-node cluster doesn't swallow the canvas).
+ */
+export function supernodeSvgRadius(memberCount: number): number {
+  return Math.min(7, 2.2 + Math.sqrt(Math.max(1, memberCount)) * 0.7);
+}
+
+/** Same radius mapped onto sigma's pixel sizing. */
+export function supernodeSigmaSize(memberCount: number): number {
+  return supernodeSvgRadius(memberCount) * SIGMA_SIZE_FACTOR;
+}
+
 // ─── colour utilities (sigma's WebGL colour parser handles hex/rgb(a) but not
 //     hsl(), so community tints are converted up front) ─────────────────────
 
@@ -159,6 +177,10 @@ export interface SigmaNodeAttributes {
   nodeType: string;
   community: number;
   orphan: boolean;
+  /** True for a collapsed-community supernode; always labels, never dims away. */
+  isSupernode: boolean;
+  /** Member count behind a supernode (0 for ordinary nodes). */
+  memberCount: number;
   /** Drives `defaultNodeType` → NodeBorderProgram. */
   type: "border";
 }
@@ -169,7 +191,19 @@ export interface SigmaEdgeAttributes {
   /** Original edge label, kept so the reducer can surface it on focus only. */
   edgeLabel: string;
   label: string;
-  type: "line";
+  /**
+   * True when the edge's endpoints sit in different communities — the
+   * group-in-a-box overlay routes these at the box borders, so the native
+   * straight edge is hidden while that mode is on.
+   */
+  crossCommunity: boolean;
+  /**
+   * Bundling curvature consumed by @sigma/edge-curve when bundling is on. 0 for
+   * a straight chord; the reducer flips the edge to the "curved" program only
+   * when bundling is active.
+   */
+  curvature: number;
+  type: "line" | "curved";
 }
 
 export interface BuildSigmaGraphParams {
@@ -180,6 +214,12 @@ export interface BuildSigmaGraphParams {
   orphanIds: Set<string>;
   dark?: boolean;
   edgeColor?: string;
+  /**
+   * Per-edge bundling curvature (sigma scene space), keyed by edge id. When
+   * present and non-zero, the edge carries the value so the curve program can
+   * bow it onto its bundle. Absent / 0 → straight edge.
+   */
+  bundledCurvatures?: Map<string, number>;
 }
 
 /**
@@ -199,6 +239,7 @@ export function buildSigmaGraph(
     orphanIds,
     dark = true,
     edgeColor = "#3a424d",
+    bundledCurvatures,
   } = params;
 
   const graph = new Graph<SigmaNodeAttributes, SigmaEdgeAttributes>({
@@ -212,7 +253,12 @@ export function buildSigmaGraph(
     const type = String(node.data.node_type ?? "node");
     const incomingScale = sizeScales.get(node.id) ?? 1;
     const pos = layout.get(node.id);
-    const size = sigmaNodeSize(type, incomingScale);
+    const isSupernode = node.data.__supernode === true;
+    const memberCount =
+      typeof node.data.__memberCount === "number" ? node.data.__memberCount : 0;
+    const size = isSupernode
+      ? supernodeSigmaSize(memberCount)
+      : sigmaNodeSize(type, incomingScale);
     const fill = pos
       ? sigmaColorForCommunity(pos.community, dark)
       : colorForType(type);
@@ -224,11 +270,13 @@ export function buildSigmaGraph(
       baseSize: size,
       color: fill,
       mutedColor: withAlpha(fill, 0.14),
-      borderColor: colorForType(type),
+      borderColor: isSupernode ? SUPERNODE_STROKE_COLOR : colorForType(type),
       label: node.label,
       nodeType: type,
       community: pos?.community ?? -1,
       orphan: orphanIds.has(node.id),
+      isSupernode,
+      memberCount,
       type: "border",
     });
   }
@@ -236,11 +284,18 @@ export function buildSigmaGraph(
   for (const edge of edges) {
     if (!graph.hasNode(edge.source) || !graph.hasNode(edge.target)) continue;
     if (graph.hasEdge(edge.id)) continue;
+    const sc = layout.get(edge.source)?.community ?? -1;
+    const tc = layout.get(edge.target)?.community ?? -1;
+    const aggregated = edge.data?.__aggregated === true;
+    const weight = typeof edge.data?.weight === "number" ? edge.data.weight : 1;
     graph.addEdgeWithKey(edge.id, edge.source, edge.target, {
-      size: 1,
+      // Aggregated cross-cluster edges thicken with the number they fold in.
+      size: aggregated ? Math.min(6, 1 + Math.log2(weight + 1)) : 1,
       color: withAlpha(edgeColor, 0.34),
       edgeLabel: edge.label ?? "",
       label: "",
+      crossCommunity: sc !== tc,
+      curvature: bundledCurvatures?.get(edge.id) ?? 0,
       type: "line",
     });
   }
@@ -248,6 +303,175 @@ export function buildSigmaGraph(
   return graph;
 }
 
+// ─── group-in-a-box geometry (pure; consumed by the SVG fallback directly and
+//     by the canvas overlay after a graph→viewport transform) ────────────────
+
+export interface CommunityBox {
+  community: number;
+  /** Member count — drives nothing visual, surfaced for labels/tooltips. */
+  count: number;
+  /** Tint hue for this community (hsl string). */
+  tint: string;
+  /** Faint translucent fill so clusters read without drowning the nodes. */
+  fill: string;
+  /** Stronger translucent stroke for the box border. */
+  stroke: string;
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+  /** Box centre, handy for community labels. */
+  cx: number;
+  cy: number;
+}
+
+export interface CommunityBoxOptions {
+  /** Padding (in layout units) added around the member bounding box. */
+  padding?: number;
+  dark?: boolean;
+}
+
+/**
+ * One bounding box per community, sized to its members with a small padding.
+ * Positions are in the same [0, 100] layout space the SVG fallback draws in;
+ * the canvas overlay maps them through sigma's graph→viewport transform.
+ * Communities are returned in ascending id order so the output is stable.
+ */
+export function computeCommunityBoxes(
+  nodes: GraphNode[],
+  layout: GraphLayout,
+  options: CommunityBoxOptions = {}
+): CommunityBox[] {
+  const { padding = 2.5, dark = true } = options;
+  const bounds = new Map<
+    number,
+    { minX: number; minY: number; maxX: number; maxY: number; count: number }
+  >();
+
+  for (const node of nodes) {
+    const pos = layout.get(node.id);
+    if (!pos) continue;
+    const b = bounds.get(pos.community);
+    if (!b) {
+      bounds.set(pos.community, {
+        minX: pos.x,
+        minY: pos.y,
+        maxX: pos.x,
+        maxY: pos.y,
+        count: 1,
+      });
+    } else {
+      b.minX = Math.min(b.minX, pos.x);
+      b.minY = Math.min(b.minY, pos.y);
+      b.maxX = Math.max(b.maxX, pos.x);
+      b.maxY = Math.max(b.maxY, pos.y);
+      b.count += 1;
+    }
+  }
+
+  return [...bounds.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([community, b]) => {
+      const tint = colorForCommunity(community, dark);
+      return {
+        community,
+        count: b.count,
+        tint,
+        fill: withAlpha(tint, 0.08),
+        stroke: withAlpha(tint, 0.5),
+        minX: b.minX - padding,
+        minY: b.minY - padding,
+        maxX: b.maxX + padding,
+        maxY: b.maxY + padding,
+        cx: (b.minX + b.maxX) / 2,
+        cy: (b.minY + b.maxY) / 2,
+      };
+    });
+}
+
+export interface RoutedEdge {
+  id: string;
+  source: string;
+  target: string;
+  label?: string;
+  sourceCommunity: number;
+  targetCommunity: number;
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+
+interface Box {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+/**
+ * Walk the ray from `p` toward `q` and return the point where it leaves the
+ * box that contains `p`. Used to clip an inter-community edge to its source /
+ * target box borders so the segment connects the boxes rather than cutting
+ * through their interiors.
+ */
+function exitPoint(
+  px: number,
+  py: number,
+  qx: number,
+  qy: number,
+  box: Box
+): { x: number; y: number } {
+  const dx = qx - px;
+  const dy = qy - py;
+  let t = 1;
+  if (dx > 0) t = Math.min(t, (box.maxX - px) / dx);
+  else if (dx < 0) t = Math.min(t, (box.minX - px) / dx);
+  if (dy > 0) t = Math.min(t, (box.maxY - py) / dy);
+  else if (dy < 0) t = Math.min(t, (box.minY - py) / dy);
+  t = Math.max(0, Math.min(1, t));
+  return { x: px + dx * t, y: py + dy * t };
+}
+
+/**
+ * Route every inter-community edge so it runs between the two community box
+ * borders instead of node-centre to node-centre — the group-in-a-box
+ * convention that keeps cross-cluster edges out of unrelated clusters.
+ * Intra-community edges are left to the native renderer and skipped here.
+ */
+export function routeInterCommunityEdges(
+  edges: GraphEdge[],
+  layout: GraphLayout,
+  boxes: CommunityBox[]
+): RoutedEdge[] {
+  const boxByCommunity = new Map(boxes.map((b) => [b.community, b]));
+  const out: RoutedEdge[] = [];
+  for (const edge of edges) {
+    const s = layout.get(edge.source);
+    const t = layout.get(edge.target);
+    if (!s || !t) continue;
+    if (s.community === t.community) continue;
+    const sourceBox = boxByCommunity.get(s.community);
+    const targetBox = boxByCommunity.get(t.community);
+    if (!sourceBox || !targetBox) continue;
+    const start = exitPoint(s.x, s.y, t.x, t.y, sourceBox);
+    const end = exitPoint(t.x, t.y, s.x, s.y, targetBox);
+    out.push({
+      id: edge.id,
+      source: edge.source,
+      target: edge.target,
+      label: edge.label,
+      sourceCommunity: s.community,
+      targetCommunity: t.community,
+      x1: start.x,
+      y1: start.y,
+      x2: end.x,
+      y2: end.y,
+    });
+  }
+  return out;
+}
+
 // ─── focus neighbourhood (parity with the canvas focus highlight) ───────────
 
 export interface GraphFocus {
@@ -284,6 +508,13 @@ export interface SigmaReducerState {
   /** Focus-pulse progress, 0 (rest) → 1 (peak). Held at 0 for reduced motion. */
   pulse: number;
   colors: SigmaThemeColors;
+  /**
+   * Group-in-a-box mode: cross-community edges are drawn by the overlay at the
+   * box borders, so the native straight edge is hidden to avoid double lines.
+   */
+  groupInBox?: boolean;
+  /** Edge bundling on → edges render through the curve program. */
+  bundle: boolean;
 }
 
 export interface SigmaNodeDisplay {
@@ -303,6 +534,10 @@ export interface SigmaEdgeDisplay {
   forceLabel: boolean;
   zIndex: number;
   hidden: boolean;
+  /** Which edge program draws this edge: straight "line" or bundled "curved". */
+  type: "line" | "curved";
+  /** Bow magnitude/sign for the curve program (ignored by the line program). */
+  curvature: number;
 }
 
 const NODE_LABEL_MAX = 36;
@@ -337,9 +572,12 @@ export function reduceSigmaNode(
         ? colors.selectedNodeStroke
         : attrs.borderColor;
 
+  // Supernodes always carry their cluster/count label so the collapsed state
+  // is self-explanatory and obviously clickable.
   const showLabel =
-    hasFocus &&
-    (isPrimary || (focus.nodes.size <= NEIGHBOUR_LABEL_LIMIT && isNeighbor));
+    attrs.isSupernode ||
+    (hasFocus &&
+      (isPrimary || (focus.nodes.size <= NEIGHBOUR_LABEL_LIMIT && isNeighbor)));
 
   return {
     size: attrs.baseSize * scale,
@@ -347,7 +585,7 @@ export function reduceSigmaNode(
     borderColor,
     label: showLabel ? attrs.label.slice(0, NODE_LABEL_MAX) : "",
     forceLabel: showLabel,
-    zIndex: isPrimary ? 3 : isNeighbor ? 2 : 1,
+    zIndex: isPrimary ? 3 : attrs.isSupernode ? 2 : isNeighbor ? 2 : 1,
     hidden: false,
   };
 }
@@ -358,10 +596,32 @@ export function reduceSigmaEdge(
   attrs: SigmaEdgeAttributes,
   state: SigmaReducerState
 ): SigmaEdgeDisplay {
-  const { focus, focusId, colors } = state;
+  const { focus, focusId, colors, groupInBox, bundle } = state;
   const hasFocus = focusId !== null;
   const focused = focus.edges.has(id);
 
+  // The sigma edge reducer's return *replaces* the edge data, so type and
+  // curvature must be carried through on every branch or the curve program
+  // can't see them. Bundle off → always the straight line program.
+  const curvature = attrs.curvature;
+  const type: "line" | "curved" =
+    bundle && Math.abs(curvature) > 1e-4 ? "curved" : "line";
+
+  // In group-in-a-box mode the overlay owns cross-community edges; hide the
+  // native straight line so it doesn't cut through unrelated clusters.
+  if (groupInBox && attrs.crossCommunity && !focused) {
+    return {
+      size: attrs.size,
+      color: attrs.color,
+      label: "",
+      forceLabel: false,
+      zIndex: 0,
+      hidden: true,
+      type,
+      curvature,
+    };
+  }
+
   if (!hasFocus) {
     return {
       size: attrs.size,
@@ -370,6 +630,8 @@ export function reduceSigmaEdge(
       forceLabel: false,
       zIndex: 0,
       hidden: false,
+      type,
+      curvature,
     };
   }
 
@@ -381,6 +643,8 @@ export function reduceSigmaEdge(
       forceLabel: Boolean(attrs.edgeLabel),
       zIndex: 2,
       hidden: false,
+      type,
+      curvature,
     };
   }
 
@@ -391,5 +655,7 @@ export function reduceSigmaEdge(
     forceLabel: false,
     zIndex: 0,
     hidden: false,
+    type,
+    curvature,
   };
 }

package/src/lib/router.svelte.ts

@@ -14,74 +14,90 @@
 // Both implementations satisfy the same `Router` contract, so every view
 // component navigates the same way regardless of which Surface it runs in.
 
-import { getContext, setContext } from 'svelte'
-import { collectionPageHref } from './collection-pages'
+import { getContext, setContext } from "svelte";
+import { collectionPageHref } from "./collection-pages";
 
-/** The four top-level destinations of the Mountable Root. */
-export type View = 'query' | 'collections' | 'cluster' | 'security'
+/** The top-level destinations of the Mountable Root. */
+export type View =
+  | "query"
+  | "collections"
+  | "cluster"
+  | "security"
+  | "settings"
+  | "appearance";
 
 /**
  * A navigation intent. `collection` carries a selected collection + subpage
  * within the collections workspace; the other targets are the bare views.
  */
 export type RouteTarget =
-  | { view: 'query' }
-  | { view: 'collections' }
-  | { view: 'cluster' }
-  | { view: 'security' }
-  | { view: 'collection'; collection: string; subpage: string }
+  | { view: "query" }
+  | { view: "collections" }
+  | { view: "cluster" }
+  | { view: "security" }
+  | { view: "settings" }
+  | { view: "appearance" }
+  | { view: "collection"; collection: string; subpage: string };
 
 /** Resolved current location, the reactive surface views read from. */
 export interface RouteLocation {
-  view: View
+  view: View;
   /** Selected collection when inside the collections workspace, else null. */
-  collection: string | null
+  collection: string | null;
   /** Selected collection subpage (`table`, `graph`, …), else null. */
-  subpage: string | null
+  subpage: string | null;
 }
 
 export interface Router {
   /** Current top-level view. */
-  readonly view: View
+  readonly view: View;
   /** Selected collection, or null. */
-  readonly collection: string | null
+  readonly collection: string | null;
   /** Selected collection subpage, or null. */
-  readonly subpage: string | null
+  readonly subpage: string | null;
   /** Canonical path for the current location (mirrors the SvelteKit URL). */
-  readonly path: string
+  readonly path: string;
   /** The canonical href a `RouteTarget` maps to (for `<a href>` display). */
-  href(target: RouteTarget): string
+  href(target: RouteTarget): string;
   /**
    * Navigate to a target. When called from an anchor `onclick`, pass the
    * event so the router can `preventDefault()` (state router) or honour
    * modifier-clicks for open-in-new-tab (Kit router). `replace` swaps the
    * current history entry instead of pushing (Kit only; ignored by state).
    */
-  go(target: RouteTarget, event?: Event, replace?: boolean): void
+  go(target: RouteTarget, event?: Event, replace?: boolean): void;
 }
 
 /** Map a `RouteTarget` to its canonical path. */
 export function targetToHref(target: RouteTarget): string {
   switch (target.view) {
-    case 'query':
-      return '/query'
-    case 'collections':
-      return '/collections'
-    case 'cluster':
-      return '/cluster'
-    case 'security':
-      return '/security'
-    case 'collection':
-      return collectionPageHref(target.collection, target.subpage)
+    case "query":
+      return "/query";
+    case "collections":
+      return "/collections";
+    case "cluster":
+      return "/cluster";
+    case "security":
+      return "/security";
+    case "settings":
+      return "/settings";
+    case "appearance":
+      return "/appearance";
+    case "collection":
+      return collectionPageHref(target.collection, target.subpage);
   }
 }
 
 /** Map a `RouteTarget` to a resolved location. */
 export function targetToLocation(target: RouteTarget): RouteLocation {
-  if (target.view === 'collection') {
-    return { view: 'collections', collection: target.collection, subpage: target.subpage }
+  if (target.view === "collection") {
+    return {
+      view: "collections",
+      collection: target.collection,
+      subpage: target.subpage,
+    };
   }
-  return { view: target.view, collection: null, subpage: null }
+  return { view: target.view, collection: null, subpage: null };
 }
 
 /**
@@ -90,18 +106,25 @@ export function targetToLocation(target: RouteTarget): RouteLocation {
  * `/collections` for the bare collections workspace.
  */
 export function pathToLocation(pathname: string): RouteLocation {
-  if (pathname.startsWith('/query')) return { view: 'query', collection: null, subpage: null }
-  if (pathname.startsWith('/cluster')) return { view: 'cluster', collection: null, subpage: null }
-  if (pathname.startsWith('/security')) return { view: 'security', collection: null, subpage: null }
-  const m = pathname.match(/^\/c\/([^/]+)(?:\/p\/([^/]+))?/)
+  if (pathname.startsWith("/query"))
+    return { view: "query", collection: null, subpage: null };
+  if (pathname.startsWith("/cluster"))
+    return { view: "cluster", collection: null, subpage: null };
+  if (pathname.startsWith("/security"))
+    return { view: "security", collection: null, subpage: null };
+  if (pathname.startsWith("/settings"))
+    return { view: "settings", collection: null, subpage: null };
+  if (pathname.startsWith("/appearance"))
+    return { view: "appearance", collection: null, subpage: null };
+  const m = pathname.match(/^\/c\/([^/]+)(?:\/p\/([^/]+))?/);
   if (m) {
     return {
-      view: 'collections',
+      view: "collections",
       collection: decodeURIComponent(m[1]),
       subpage: m[2] ? decodeURIComponent(m[2]) : null,
-    }
+    };
   }
-  return { view: 'collections', collection: null, subpage: null }
+  return { view: "collections", collection: null, subpage: null };
 }
 
 /**
@@ -111,43 +134,47 @@ export function pathToLocation(pathname: string): RouteLocation {
  */
 export function createStateRouter(initial?: RouteLocation): Router {
   let loc = $state<RouteLocation>(
-    initial ?? { view: 'collections', collection: null, subpage: null },
-  )
+    initial ?? { view: "collections", collection: null, subpage: null }
+  );
   return {
     get view() {
-      return loc.view
+      return loc.view;
     },
     get collection() {
-      return loc.collection
+      return loc.collection;
     },
     get subpage() {
-      return loc.subpage
+      return loc.subpage;
     },
     get path() {
       return targetToHref(
         loc.collection
-          ? { view: 'collection', collection: loc.collection, subpage: loc.subpage ?? 'table' }
-          : { view: loc.view },
-      )
+          ? {
+              view: "collection",
+              collection: loc.collection,
+              subpage: loc.subpage ?? "table",
+            }
+          : { view: loc.view }
+      );
     },
     href: (target) => targetToHref(target),
     go: (target, event) => {
       // The href is synthetic in state mode, so always suppress the anchor's
       // default navigation and switch the in-memory location instead.
-      event?.preventDefault()
-      loc = targetToLocation(target)
+      event?.preventDefault();
+      loc = targetToLocation(target);
     },
-  }
+  };
 }
 
-const ROUTER_KEY = Symbol('red-ui-router')
+const ROUTER_KEY = Symbol("red-ui-router");
 
-let fallbackRouter: Router | null = null
+let fallbackRouter: Router | null = null;
 
 /** Provide a router to descendant view components (called by the Mountable Root). */
 export function setRouter(router: Router): Router {
-  setContext(ROUTER_KEY, router)
-  return router
+  setContext(ROUTER_KEY, router);
+  return router;
 }
 
 /**
@@ -156,8 +183,8 @@ export function setRouter(router: Router): Router {
  * lack of a provider.
  */
 export function useRouter(): Router {
-  const router = getContext<Router | undefined>(ROUTER_KEY)
-  if (router) return router
-  if (!fallbackRouter) fallbackRouter = createStateRouter()
-  return fallbackRouter
+  const router = getContext<Router | undefined>(ROUTER_KEY);
+  if (router) return router;
+  if (!fallbackRouter) fallbackRouter = createStateRouter();
+  return fallbackRouter;
 }