@grafloria/element 0.3.18 → 0.3.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafloria/element",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "type": "commonjs",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -11,7 +11,7 @@
   "dependencies": {
     "tslib": "^2.3.0"
   },
-  "description": "The <grafloria-flow> custom element and high-level diagram kits (dashboard, UML, ERD) — works in any framework or none",
+  "description": "The <grafloria-flow> custom element and high-level diagram kits (dashboard, UML, ERD) \u2014 works in any framework or none",
   "license": "MIT",
   "author": "Ramy Othman",
   "homepage": "https://github.com/grafloria/grafloria",
@@ -38,5 +38,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "module": "./esm/src/index.js"
-}
+  "module": "./esm/src/index.js",
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "esm/**/*.js"
+  ],
+  "sideEffects": [
+    "./src/index.js",
+    "./esm/src/index.js"
+  ]
+}

package/src/index.d.ts

@@ -74,7 +74,8 @@ export { GroupModel } from '@grafloria/engine';
 export { GroupCollapseService, PROXY_NODE_GROUP_KEY, PROXY_LINK_GROUP_KEY } from '@grafloria/engine';
 export { serveLayout } from '@grafloria/engine';
 export type { LayoutPort, LayoutServePort, LayoutProgress } from '@grafloria/engine';
-export { erDiagram, erRowCenterY, ER_ROW_H, ER_HEAD_H, umlDiagram, ensureDiagramKitStyles, DIAGRAM_KIT_STYLE_ID, updateEntity, updateClass, addColumnAt, removeColumnAt, renameColumnAt, bindCardEditing, matchColumns, rowIndexFromY, } from './lib/diagram-kit';
+export { erDiagram, erRowCenterY, ER_ROW_H, ER_HEAD_H, umlDiagram, ensureDiagramKitStyles, DIAGRAM_KIT_STYLE_ID, updateEntity, updateClass, addColumnAt, removeColumnAt, renameColumnAt, bindCardEditing, matchColumns, rowIndexFromY, scoreMatch, matchTier, assignTiers, singularize, bindJoinGuidance, ensureJoinGuidanceStyles, JOIN_GUIDANCE_STYLE_ID, } from './lib/diagram-kit';
+export type { JoinColumn, JoinEnd, MatchTier, JoinGuidanceApi, JoinGuidanceOptions, JoinGuidanceHandle, } from './lib/diagram-kit';
 export type { ErColumn, ErEntitySpec, ErRelationshipSpec, ErCardinality, ErSide, ErDiagramOptions, UmlClassSpec, UmlRelationshipSpec, UmlRelationKind, UmlSide, UmlDiagramOptions, ErEntityDelta, UmlClassDelta, CardEditingHandle, } from './lib/diagram-kit';
 export { erTable, umlClass, erTables, umlClasses, CardHandle, ErTable, ErField, ErColumnList, UmlClass, UmlMemberList, } from './lib/diagram-kit';
 export type { HandleApi } from './lib/diagram-kit';

package/src/index.js

@@ -18,8 +18,8 @@ exports.tailwindBridge = exports.muiBridge = exports.shadcnBridge = exports.deri
 exports.embedModelInSvg = exports.GRAFLORIA_MODEL_KEY = exports.GRAFLORIA_NS = exports.mimeTypeForFormat = exports.svgToDataUri = exports.canRasterizeInThisEnvironment = exports.resolveRasterBackend = exports.createDomRasterBackend = exports.exportBatch = exports.buildPrintDocument = exports.paginate = exports.exportPdf = exports.vnodeBounds = exports.serializeVNode = exports.exportSvg = exports.instanceScopeSelector = exports.resolveThemeVars = exports.themeVarValue = exports.themeVar = exports.cssVarName = exports.THEME_TOKENS = exports.THEME_VARS = exports.GRAFLORIA_VAR_PREFIX = exports.GRAFLORIA_INSTANCE_ATTR = exports.CASCADE_ORDER = exports.resolveLinkStyle = exports.resolveNodeStyle = exports.resolveStyleClasses = exports.listStyles = exports.clearStyles = exports.removeStyle = exports.hasStyle = exports.getStyle = exports.defineStyles = exports.defineStyle = exports.registerTemplateLibrary = exports.NodeFactory = exports.TemplateRegistry = exports.generatedTemplates = exports.registerGeneratedTemplates = exports.registerStencils = exports.getStencil = exports.builtInStencils = exports.listStencils = exports.portTypeColor = exports.arePortDataTypesCompatible = exports.portTypeRegistry = exports.generateInstanceOverrideCSS = exports.generateTokenBridgeBlock = exports.BRIDGEABLE_TOKENS = void 0;
 exports.exportDiagramText = exports.CommentStore = exports.opId = exports.compareOps = exports.replay = exports.applyOp = exports.LamportClock = exports.ReferentialIntegrity = exports.UndoStack = exports.OpLog = exports.LwwRegistry = exports.Replica = exports.CausalBuffer = exports.OpBatcher = exports.VersionVector = exports.Awareness = exports.UnreliableHub = exports.WebSocketTransport = exports.BroadcastChannelTransport = exports.MemoryTransport = exports.MemoryHub = exports.SyncAdapter = exports.createSyncSession = exports.loadReadonlySnapshot = exports.isDocumentLocked = exports.lockDocument = exports.followPresenter = exports.presentTo = exports.InMemoryViewportChannel = exports.CommentOverlayController = exports.contrastingTextColor = exports.actorInitials = exports.actorColor = exports.PRESENCE_LAYER_CLASS = exports.PresenceOverlay = exports.bindPresence = exports.QualityGovernor = exports.EMPTY_SNAPSHOT = exports.formatSnapshot = exports.PerfHud = exports.createBackground = exports.createControls = exports.createMiniMap = exports.attachCanvasPlugins = exports.importDiagram = exports.isEditableArtifact = exports.extractModel = exports.extractModelFromPng = exports.embedModelInPng = exports.extractModelFromSvg = void 0;
 exports.onShapeRegistryChange = exports.getShapeRegistryVersion = exports.getShapeDefinition = exports.listShapes = exports.hasShape = exports.getShape = exports.unregisterShape = exports.registerPathShape = exports.registerShape = exports.createCounterScaledPortal = exports.createViewportPortal = exports.createPortal = exports.INK_OVERLAY_CLASS = exports.InkOverlay = exports.StrokeEditTool = exports.EraserTool = exports.RectangleTool = exports.DrawTool = exports.createStrokeEditTool = exports.createEraserTool = exports.createRectangleTool = exports.createDrawTool = exports.listTools = exports.registerTool = exports.clearConnectionValidators = exports.isValidConnection = exports.registerConnectionValidator = exports.listConnectors = exports.registerConnector = exports.listConnectionPoints = exports.registerConnectionPoint = exports.listAnchors = exports.registerAnchor = exports.htmlLabelVNode = exports.listMarkers = exports.unregisterMarker = exports.registerMarker = exports.listLabelTemplates = exports.unregisterLabelTemplate = exports.registerLabelTemplate = exports.listLinkTemplates = exports.unregisterLinkTemplate = exports.registerLinkTemplate = exports.DEFAULT_STROKE_STYLE = exports.StrokeModel = exports.DiagramSerializer = exports.GRAFLORIA_HASH_PREFIX = exports.GRAFLORIA_DOC_PREFIX = exports.stripGrafloriaSidecar = exports.importDiagramText = void 0;
-exports.rowHeightFor = exports.bindDashboardGrid = exports.UmlMemberList = exports.UmlClass = exports.ErColumnList = exports.ErField = exports.ErTable = exports.CardHandle = exports.umlClasses = exports.erTables = exports.umlClass = exports.erTable = exports.rowIndexFromY = exports.matchColumns = exports.bindCardEditing = exports.renameColumnAt = exports.removeColumnAt = exports.addColumnAt = exports.updateClass = exports.updateEntity = exports.DIAGRAM_KIT_STYLE_ID = exports.ensureDiagramKitStyles = exports.umlDiagram = exports.ER_HEAD_H = exports.ER_ROW_H = exports.erRowCenterY = exports.erDiagram = exports.serveLayout = exports.PROXY_LINK_GROUP_KEY = exports.PROXY_NODE_GROUP_KEY = exports.GroupCollapseService = exports.GroupModel = exports.SwimlaneService = exports.DEFAULT_SNAP_CONFIG = exports.SnapController = exports.buildHtmlForeignObject = exports.hasHtmlContent = exports.getHtmlContent = exports.resolveToolbar = exports.getNodeToolbar = exports.autoSizeDiagram = exports.autoSizeNode = exports.outerSizeForInner = exports.desiredNodeSize = exports.measureLabelContent = exports.clampValue = exports.clampSizeToConstraints = exports.resolveAspectRatio = exports.isAutoSized = exports.getNodeSizing = void 0;
-exports.coalesceRects = exports.rotatePointSelection = exports.distanceToSegmentCanvas = exports.coalesce = exports.rotatePoint = exports.distanceToSegment = exports.PortModel = exports.NodeModel = exports.ensureStencilKitStyles = exports.bindShapeDataPanel = exports.bindStencilPalette = exports.BUILT_IN_WIDGET_KINDS = exports.renderTableWidget = exports.renderFunnelWidget = exports.renderDonutWidget = exports.renderBarWidget = exports.renderLineWidget = exports.renderKpiWidget = exports.defaultWidgetRenderer = exports.dashboard = exports.DASHBOARD_KIT_STYLE_ID = exports.ensureDashboardKitStyles = exports.buildCommitCommands = exports.cellFromGridItem = exports.gridItemFromCell = exports.sizeToSpan = exports.pointToCell = exports.cellToRect = exports.columnUnitFor = exports.boardHeightFor = void 0;
+exports.CardHandle = exports.umlClasses = exports.erTables = exports.umlClass = exports.erTable = exports.JOIN_GUIDANCE_STYLE_ID = exports.ensureJoinGuidanceStyles = exports.bindJoinGuidance = exports.singularize = exports.assignTiers = exports.matchTier = exports.scoreMatch = exports.rowIndexFromY = exports.matchColumns = exports.bindCardEditing = exports.renameColumnAt = exports.removeColumnAt = exports.addColumnAt = exports.updateClass = exports.updateEntity = exports.DIAGRAM_KIT_STYLE_ID = exports.ensureDiagramKitStyles = exports.umlDiagram = exports.ER_HEAD_H = exports.ER_ROW_H = exports.erRowCenterY = exports.erDiagram = exports.serveLayout = exports.PROXY_LINK_GROUP_KEY = exports.PROXY_NODE_GROUP_KEY = exports.GroupCollapseService = exports.GroupModel = exports.SwimlaneService = exports.DEFAULT_SNAP_CONFIG = exports.SnapController = exports.buildHtmlForeignObject = exports.hasHtmlContent = exports.getHtmlContent = exports.resolveToolbar = exports.getNodeToolbar = exports.autoSizeDiagram = exports.autoSizeNode = exports.outerSizeForInner = exports.desiredNodeSize = exports.measureLabelContent = exports.clampValue = exports.clampSizeToConstraints = exports.resolveAspectRatio = exports.isAutoSized = exports.getNodeSizing = void 0;
+exports.coalesceRects = exports.rotatePointSelection = exports.distanceToSegmentCanvas = exports.coalesce = exports.rotatePoint = exports.distanceToSegment = exports.PortModel = exports.NodeModel = exports.ensureStencilKitStyles = exports.bindShapeDataPanel = exports.bindStencilPalette = exports.BUILT_IN_WIDGET_KINDS = exports.renderTableWidget = exports.renderFunnelWidget = exports.renderDonutWidget = exports.renderBarWidget = exports.renderLineWidget = exports.renderKpiWidget = exports.defaultWidgetRenderer = exports.dashboard = exports.DASHBOARD_KIT_STYLE_ID = exports.ensureDashboardKitStyles = exports.buildCommitCommands = exports.cellFromGridItem = exports.gridItemFromCell = exports.sizeToSpan = exports.pointToCell = exports.cellToRect = exports.columnUnitFor = exports.boardHeightFor = exports.rowHeightFor = exports.bindDashboardGrid = exports.UmlMemberList = exports.UmlClass = exports.ErColumnList = exports.ErField = exports.ErTable = void 0;
 const tslib_1 = require("tslib");
 const grafloria_flow_element_1 = require("./lib/grafloria-flow-element");
 var grafloria_flow_element_2 = require("./lib/grafloria-flow-element");
@@ -448,6 +448,15 @@ Object.defineProperty(exports, "renameColumnAt", { enumerable: true, get: functi
 Object.defineProperty(exports, "bindCardEditing", { enumerable: true, get: function () { return diagram_kit_1.bindCardEditing; } });
 Object.defineProperty(exports, "matchColumns", { enumerable: true, get: function () { return diagram_kit_1.matchColumns; } });
 Object.defineProperty(exports, "rowIndexFromY", { enumerable: true, get: function () { return diagram_kit_1.rowIndexFromY; } });
+// Live join guidance (query-builder): score every other table's columns
+// against a connection drag's source column and tint the kit rows by fit.
+Object.defineProperty(exports, "scoreMatch", { enumerable: true, get: function () { return diagram_kit_1.scoreMatch; } });
+Object.defineProperty(exports, "matchTier", { enumerable: true, get: function () { return diagram_kit_1.matchTier; } });
+Object.defineProperty(exports, "assignTiers", { enumerable: true, get: function () { return diagram_kit_1.assignTiers; } });
+Object.defineProperty(exports, "singularize", { enumerable: true, get: function () { return diagram_kit_1.singularize; } });
+Object.defineProperty(exports, "bindJoinGuidance", { enumerable: true, get: function () { return diagram_kit_1.bindJoinGuidance; } });
+Object.defineProperty(exports, "ensureJoinGuidanceStyles", { enumerable: true, get: function () { return diagram_kit_1.ensureJoinGuidanceStyles; } });
+Object.defineProperty(exports, "JOIN_GUIDANCE_STYLE_ID", { enumerable: true, get: function () { return diagram_kit_1.JOIN_GUIDANCE_STYLE_ID; } });
 // Typed façade handles (domain-API decision, Option B): the OO surface —
 // CardHandle → ErTable/UmlClass, ErField — over the data-first kit.
 var diagram_kit_2 = require("./lib/diagram-kit");

package/src/lib/dashboard-kit/grid-binder.js

@@ -676,27 +676,28 @@ function bindDashboardGrid(api, group, options = {}) {
     };
     const commitGesture = (g) => {
         var _a;
-        // Snap the ghost into its engine cell — the instant, truthful drop.
-        const item = engine.getItem(g.id);
-        if (item) {
-            writing = true;
-            try {
-                writeRect(g.id, (0, grid_mapping_1.cellToRect)(item, frame(), geom(), rows()));
-            }
-            finally {
-                writing = false;
-            }
-        }
+        // SETTLE FIRST, then measure. Mid-drag the board can transiently hold more
+        // rows than the drop keeps (hover above a locked slab pushes everything
+        // down), and fit-mode row height shrinks with it — every displaced tile is
+        // re-projected at that TRANSIENT height. The old order computed the commit
+        // deltas from those pixels and, when the engine settled back with no cell
+        // changes, nothing ever wrote the pixels back: a refused drop left the
+        // whole board at the mid-drag height, KPI value lines clipped to nothing
+        // (live audit repro: drag the trend chart above the KPI row → every widget
+        // 122px→85px with identical cells). endGesture() keeps the settled cells;
+        // project() then derives every member's pixels — the ghost included — from
+        // that truth, so the deltas below record settled geometry and undo/redo
+        // both replay it faithfully.
+        engine.endGesture();
+        cleanupGestureVisuals(g);
+        gesture = null;
+        project();
         const deltas = deltasSince(g.startCells, g.startGeom);
         const commands = (0, grid_mapping_1.buildCommitCommands)(deltas);
         if (g.esc && g.esc.rowsAdded !== 0) {
             commands.push(new SetGroupCellCommand(group.id, g.esc.cellBefore, g.esc.cellAfter, g.esc.frameBefore, g.esc.frameAfter));
         }
         const changed = execute(g.kind === 'resize' ? 'Resize widget' : 'Move widget', commands);
-        engine.endGesture();
-        cleanupGestureVisuals(g);
-        gesture = null;
-        enforceBoardHeight();
         api.renderNow();
         (_a = options.onGesture) === null || _a === void 0 ? void 0 : _a.call(options, { type: 'commit', kind: g.kind, nodeId: g.id, changed });
     };

package/src/lib/dashboard-kit/styles.js

@@ -148,9 +148,15 @@ const CSS = `
 }
 
 /* kpi: value + delta stack, the spark yields its height before they do */
-.axdb-widget-b.axdb-kpi { display: flex; flex-direction: column; }
-.axdb-kpi-v { font: 700 30px/1.05 system-ui, sans-serif; letter-spacing: -.02em; color: var(--axdb-ink); }
-.axdb-kpi-d { margin-top: 6px; font: 600 12px/1.2 system-ui, sans-serif; }
+/* A SIZE CONTAINER, so the card's type scales with the tile instead of
+   clipping. Fit-mode shrinks tiles when rows are added (dropping a chart above
+   the KPI row took these from 122px to 85px) and fixed 30px/12px lines were
+   sliced mid-glyph by the card's overflow — the audited "trimmed" widgets.
+   cqh = 1% of the body's own height, clamped so full-size tiles look exactly
+   as before and short tiles compress instead of cutting. */
+.axdb-widget-b.axdb-kpi { display: flex; flex-direction: column; container-type: size; }
+.axdb-kpi-v { font: 700 clamp(15px, 44cqh, 30px)/1.05 system-ui, sans-serif; letter-spacing: -.02em; color: var(--axdb-ink); }
+.axdb-kpi-d { margin-top: clamp(1px, 5cqh, 6px); font: 600 clamp(9px, 19cqh, 12px)/1.2 system-ui, sans-serif; }
 .axdb-kpi-d span { color: var(--axdb-muted); font-weight: 500; }
 .axdb-kpi-d.up { color: #12a150; }
 .axdb-kpi-d.down { color: #e11d48; }

package/src/lib/diagram-kit/index.d.ts

@@ -6,4 +6,5 @@ export { updateEntity, updateClass, addColumnAt, removeColumnAt, renameColumnAt,
 export { bindCardEditing, type CardEditingHandle } from './editing';
 export { matchColumns, rowIndexFromY } from './card';
 export { entityCardContent, entityAutoHeight, classCardContent, classAutoHeight } from './card';
+export { scoreMatch, matchTier, assignTiers, singularize, bindJoinGuidance, ensureJoinGuidanceStyles, JOIN_GUIDANCE_STYLE_ID, type JoinColumn, type JoinEnd, type MatchTier, type JoinGuidanceApi, type JoinGuidanceOptions, type JoinGuidanceHandle, } from './join-guidance';
 export { erTable, umlClass, erTables, umlClasses, CardHandle, ErTable, ErField, ErColumnList, UmlClass, UmlMemberList, type HandleApi, } from './handles';

package/src/lib/diagram-kit/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UmlMemberList = exports.UmlClass = exports.ErColumnList = exports.ErField = exports.ErTable = exports.CardHandle = exports.umlClasses = exports.erTables = exports.umlClass = exports.erTable = exports.classAutoHeight = exports.classCardContent = exports.entityAutoHeight = exports.entityCardContent = exports.rowIndexFromY = exports.matchColumns = exports.bindCardEditing = exports.renameColumnAt = exports.removeColumnAt = exports.addColumnAt = exports.updateClass = exports.updateEntity = exports.bindRowInteractions = exports.DIAGRAM_KIT_STYLE_ID = exports.ensureDiagramKitStyles = exports.umlDiagram = exports.ER_HEAD_H = exports.ER_ROW_H = exports.erRowCenterY = exports.erDiagram = void 0;
+exports.UmlMemberList = exports.UmlClass = exports.ErColumnList = exports.ErField = exports.ErTable = exports.CardHandle = exports.umlClasses = exports.erTables = exports.umlClass = exports.erTable = exports.JOIN_GUIDANCE_STYLE_ID = exports.ensureJoinGuidanceStyles = exports.bindJoinGuidance = exports.singularize = exports.assignTiers = exports.matchTier = exports.scoreMatch = exports.classAutoHeight = exports.classCardContent = exports.entityAutoHeight = exports.entityCardContent = exports.rowIndexFromY = exports.matchColumns = exports.bindCardEditing = exports.renameColumnAt = exports.removeColumnAt = exports.addColumnAt = exports.updateClass = exports.updateEntity = exports.bindRowInteractions = exports.DIAGRAM_KIT_STYLE_ID = exports.ensureDiagramKitStyles = exports.umlDiagram = exports.ER_HEAD_H = exports.ER_ROW_H = exports.erRowCenterY = exports.erDiagram = void 0;
 var er_1 = require("./er");
 Object.defineProperty(exports, "erDiagram", { enumerable: true, get: function () { return er_1.erDiagram; } });
 Object.defineProperty(exports, "erRowCenterY", { enumerable: true, get: function () { return er_1.erRowCenterY; } });
@@ -31,6 +31,16 @@ Object.defineProperty(exports, "entityCardContent", { enumerable: true, get: fun
 Object.defineProperty(exports, "entityAutoHeight", { enumerable: true, get: function () { return card_2.entityAutoHeight; } });
 Object.defineProperty(exports, "classCardContent", { enumerable: true, get: function () { return card_2.classCardContent; } });
 Object.defineProperty(exports, "classAutoHeight", { enumerable: true, get: function () { return card_2.classAutoHeight; } });
+// Live join guidance — score every other table's columns against a connection
+// drag's source column and tint the kit rows by fit (the query-builder story).
+var join_guidance_1 = require("./join-guidance");
+Object.defineProperty(exports, "scoreMatch", { enumerable: true, get: function () { return join_guidance_1.scoreMatch; } });
+Object.defineProperty(exports, "matchTier", { enumerable: true, get: function () { return join_guidance_1.matchTier; } });
+Object.defineProperty(exports, "assignTiers", { enumerable: true, get: function () { return join_guidance_1.assignTiers; } });
+Object.defineProperty(exports, "singularize", { enumerable: true, get: function () { return join_guidance_1.singularize; } });
+Object.defineProperty(exports, "bindJoinGuidance", { enumerable: true, get: function () { return join_guidance_1.bindJoinGuidance; } });
+Object.defineProperty(exports, "ensureJoinGuidanceStyles", { enumerable: true, get: function () { return join_guidance_1.ensureJoinGuidanceStyles; } });
+Object.defineProperty(exports, "JOIN_GUIDANCE_STYLE_ID", { enumerable: true, get: function () { return join_guidance_1.JOIN_GUIDANCE_STYLE_ID; } });
 var handles_1 = require("./handles");
 Object.defineProperty(exports, "erTable", { enumerable: true, get: function () { return handles_1.erTable; } });
 Object.defineProperty(exports, "umlClass", { enumerable: true, get: function () { return handles_1.umlClass; } });

package/src/lib/diagram-kit/join-guidance.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Join guidance — live "which column should I join to?" scoring + tinting for
+ * kit table cards, the feature a visual query builder is actually about.
+ *
+ * Ported verbatim from a production BI tool's Query Studio (the scoring is ~55
+ * pure lines there too). While a connection drag is in progress, every column
+ * on every OTHER table is scored against the drag's source column and its card
+ * row is tinted by tier:
+ *
+ *   score 3 — PK↔FK naming convention: `orders.customer_id` ↔ `customers.id`
+ *             (`<singular(table)>_id` on one end, `id` on the other), or exact
+ *             FK column-name equality across tables;
+ *   score 2 — a PK flag on one end and an FK flag on the other;
+ *   score 1 — same column name, or both names end in "id";
+ *   score 0 — same table, or nothing.
+ *
+ * Tiers: the single best candidate scoring >= 2 is `top` (gold, "★ BEST"),
+ * every other >= 2 is `good` (green), 1 is `ok` (blue), 0 is `none` (dimmed).
+ * The SOURCE table is never tinted, and every tint clears when the drag ends —
+ * complete, cancelled or escaped.
+ *
+ * Split the same way the rest of the kit is:
+ *   - `scoreMatch` / `matchTier` / `assignTiers` / `singularize` are PURE
+ *     (unit-specced in the element suite);
+ *   - `bindJoinGuidance(api)` is the runtime: it listens to the engine's own
+ *     connection lifecycle events (`connection:start` / `:complete` /
+ *     `:cancel`) and paints tier classes onto the kit's `.axk-row` elements.
+ *
+ * Row tints go on as DOM classes — the renderer's foreignObject subtrees are
+ * patch-opaque, so classes survive the per-frame VNode patch. Port tints go in
+ * as a generated per-drag <style> element keyed by `data-port-id`: port glyphs
+ * ARE re-patched every frame, so a class added to the SVG element would be
+ * wiped mid-drag, while a stylesheet wins the cascade and survives.
+ */
+export interface JoinColumn {
+    name: string;
+    pk?: boolean;
+    fk?: boolean;
+}
+/** One end of a candidate join: a table (node) and one of its columns. */
+export interface JoinEnd {
+    table: string;
+    column: JoinColumn;
+}
+export type MatchTier = 'top' | 'good' | 'ok' | 'none';
+/** Naive English singular — enough for schema names (orders, categories, statuses). */
+export declare function singularize(word: string): string;
+/**
+ * Score a candidate join between two columns. Pure; the exact production
+ * logic. Higher is better; 0 means "no reason to join these".
+ */
+export declare function scoreMatch(a: JoinEnd, b: JoinEnd): 0 | 1 | 2 | 3;
+/** Per-score tier (rank-free half; `assignTiers` promotes the single best to `top`). */
+export declare function matchTier(score: number): Exclude<MatchTier, 'top'>;
+/**
+ * Tier every candidate score at once: the FIRST candidate holding the maximum
+ * score is `top` when that maximum is >= 2 — exactly one gold row per drag.
+ */
+export declare function assignTiers(scores: number[]): MatchTier[];
+export declare const JOIN_GUIDANCE_STYLE_ID = "grafloria-join-guidance-styles";
+/** Inject the guidance tint stylesheet once. Safe to call repeatedly / in SSR. */
+export declare function ensureJoinGuidanceStyles(doc?: Document | undefined): void;
+interface NodeLike {
+    id: string;
+    getMetadata?(key: string): unknown;
+    getPorts?(): Array<{
+        id: string;
+    }>;
+    getPort?(id: string): unknown;
+}
+/** The slice of DiagramInstance the binding needs (matches HandleApi's shape). */
+export interface JoinGuidanceApi {
+    container: HTMLElement;
+    getModel(): {
+        getNode(id: string): NodeLike | undefined;
+        getNodes?(): NodeLike[];
+    };
+    getEngine?(): {
+        eventBus?: {
+            on(event: string, handler: (data: unknown) => void): () => void;
+        };
+    } | undefined;
+}
+export interface JoinGuidanceOptions {
+    /**
+     * Resolve a PORT id to its table column. The default understands both the
+     * ER kit's convention (`TABLE__col__side__n`) and the query-builder dot
+     * convention (`table.col-in` / `table.col-out`), checked against the node's
+     * actual `kitEntity` columns so an ambiguous name never mis-resolves.
+     */
+    resolvePort?: (portId: string, nodeId: string | undefined) => {
+        nodeId: string;
+        column: string;
+    } | null;
+    /** Text of the gold chip on the best row. Default `'★ BEST'`. */
+    chipText?: string;
+    /**
+     * Extra per-tier CSS for the target columns' PORT glyphs, injected per drag.
+     * Default paints the production glows (gold/green/blue drop-shadows).
+     */
+    portCss?: (tier: MatchTier, selector: string) => string;
+}
+export interface JoinGuidanceHandle {
+    /** nodeId → rowIndex → tier for the drag in progress (empty when idle). */
+    activeTiers(): Map<string, Map<number, MatchTier>>;
+    dispose(): void;
+}
+/**
+ * Bind live join guidance to a diagram instance. Listens to the engine's
+ * connection lifecycle; while a drag is live, every kit-card row on every
+ * other table wears its tier class (and the best one its "★ BEST" chip), and
+ * the matching port glyphs glow via a generated stylesheet. Everything clears
+ * when the drag ends, however it ends.
+ */
+export declare function bindJoinGuidance(api: JoinGuidanceApi, options?: JoinGuidanceOptions): JoinGuidanceHandle;
+export {};

package/src/lib/diagram-kit/join-guidance.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * Join guidance — live "which column should I join to?" scoring + tinting for
+ * kit table cards, the feature a visual query builder is actually about.
+ *
+ * Ported verbatim from a production BI tool's Query Studio (the scoring is ~55
+ * pure lines there too). While a connection drag is in progress, every column
+ * on every OTHER table is scored against the drag's source column and its card
+ * row is tinted by tier:
+ *
+ *   score 3 — PK↔FK naming convention: `orders.customer_id` ↔ `customers.id`
+ *             (`<singular(table)>_id` on one end, `id` on the other), or exact
+ *             FK column-name equality across tables;
+ *   score 2 — a PK flag on one end and an FK flag on the other;
+ *   score 1 — same column name, or both names end in "id";
+ *   score 0 — same table, or nothing.
+ *
+ * Tiers: the single best candidate scoring >= 2 is `top` (gold, "★ BEST"),
+ * every other >= 2 is `good` (green), 1 is `ok` (blue), 0 is `none` (dimmed).
+ * The SOURCE table is never tinted, and every tint clears when the drag ends —
+ * complete, cancelled or escaped.
+ *
+ * Split the same way the rest of the kit is:
+ *   - `scoreMatch` / `matchTier` / `assignTiers` / `singularize` are PURE
+ *     (unit-specced in the element suite);
+ *   - `bindJoinGuidance(api)` is the runtime: it listens to the engine's own
+ *     connection lifecycle events (`connection:start` / `:complete` /
+ *     `:cancel`) and paints tier classes onto the kit's `.axk-row` elements.
+ *
+ * Row tints go on as DOM classes — the renderer's foreignObject subtrees are
+ * patch-opaque, so classes survive the per-frame VNode patch. Port tints go in
+ * as a generated per-drag <style> element keyed by `data-port-id`: port glyphs
+ * ARE re-patched every frame, so a class added to the SVG element would be
+ * wiped mid-drag, while a stylesheet wins the cascade and survives.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOIN_GUIDANCE_STYLE_ID = void 0;
+exports.singularize = singularize;
+exports.scoreMatch = scoreMatch;
+exports.matchTier = matchTier;
+exports.assignTiers = assignTiers;
+exports.ensureJoinGuidanceStyles = ensureJoinGuidanceStyles;
+exports.bindJoinGuidance = bindJoinGuidance;
+/** Naive English singular — enough for schema names (orders, categories, statuses). */
+function singularize(word) {
+    const w = word.toLowerCase();
+    if (w.endsWith('ies') && w.length > 3)
+        return w.slice(0, -3) + 'y';
+    if (/(?:ses|xes|zes|ches|shes)$/.test(w))
+        return w.slice(0, -2);
+    if (w.endsWith('s') && !w.endsWith('ss'))
+        return w.slice(0, -1);
+    return w;
+}
+/** The PK↔FK naming convention: `a` is `<singular(b.table)>_id` and `b` is `id`. */
+function conventionMatch(a, b) {
+    return (a.column.name.toLowerCase() === `${singularize(b.table)}_id` &&
+        b.column.name.toLowerCase() === 'id');
+}
+/**
+ * Score a candidate join between two columns. Pure; the exact production
+ * logic. Higher is better; 0 means "no reason to join these".
+ */
+function scoreMatch(a, b) {
+    if (!a || !b || a.table === b.table)
+        return 0;
+    const an = a.column.name.toLowerCase();
+    const bn = b.column.name.toLowerCase();
+    // 3 — the naming convention (either direction), or exact FK-name equality.
+    if (conventionMatch(a, b) || conventionMatch(b, a))
+        return 3;
+    if (an === bn && an.endsWith('_id') && (a.column.fk === true || b.column.fk === true))
+        return 3;
+    // 2 — PK flag on one end, FK flag on the other.
+    if ((a.column.pk === true && b.column.fk === true) || (a.column.fk === true && b.column.pk === true))
+        return 2;
+    // 1 — same name, or both look like identifiers.
+    if (an === bn)
+        return 1;
+    if (an.endsWith('id') && bn.endsWith('id'))
+        return 1;
+    return 0;
+}
+/** Per-score tier (rank-free half; `assignTiers` promotes the single best to `top`). */
+function matchTier(score) {
+    if (score >= 2)
+        return 'good';
+    if (score >= 1)
+        return 'ok';
+    return 'none';
+}
+/**
+ * Tier every candidate score at once: the FIRST candidate holding the maximum
+ * score is `top` when that maximum is >= 2 — exactly one gold row per drag.
+ */
+function assignTiers(scores) {
+    const max = scores.reduce((m, s) => (s > m ? s : m), 0);
+    let topIndex = -1;
+    if (max >= 2)
+        topIndex = scores.indexOf(max);
+    return scores.map((s, i) => (i === topIndex ? 'top' : matchTier(s)));
+}
+// ---------------------------------------------------------------------------
+// Runtime binding
+// ---------------------------------------------------------------------------
+const TIER_CLASS = {
+    top: 'axk-match-top',
+    good: 'axk-match-good',
+    ok: 'axk-match-ok',
+    none: 'axk-match-none',
+};
+const CHIP_CLASS = 'axk-match-chip';
+const PORT_STYLE_ID = 'grafloria-join-guidance-ports';
+exports.JOIN_GUIDANCE_STYLE_ID = 'grafloria-join-guidance-styles';
+/** The tier tints — the production palette, verbatim. */
+const GUIDANCE_CSS = `
+.axk-row.axk-match-top { background: #fffbeb;
+  box-shadow: inset 4px 0 0 #f59e0b, inset 0 0 0 1px #fcd34d; }
+.axk-row.axk-match-top .axk-col { font-weight: 800; color: #92600a; }
+.axk-row.axk-match-good { background: #dcfce7; box-shadow: inset 4px 0 0 #16a34a; }
+.axk-row.axk-match-good .axk-col { font-weight: 700; color: #14532d; }
+.axk-row.axk-match-ok { background: #dbeafe; box-shadow: inset 4px 0 0 #2563eb; }
+.axk-row.axk-match-none { opacity: .4; }
+.${CHIP_CLASS} { font-size: 9px; font-weight: 800; text-transform: uppercase;
+  background: #f59e0b; color: #4a2e05; border-radius: 4px; padding: 1px 4px;
+  margin-left: 4px; flex: 0 0 auto; letter-spacing: .3px; }
+`;
+/** Inject the guidance tint stylesheet once. Safe to call repeatedly / in SSR. */
+function ensureJoinGuidanceStyles(doc = typeof document !== 'undefined' ? document : undefined) {
+    if (!doc)
+        return;
+    if (doc.getElementById(exports.JOIN_GUIDANCE_STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = exports.JOIN_GUIDANCE_STYLE_ID;
+    style.textContent = GUIDANCE_CSS;
+    doc.head.appendChild(style);
+}
+const esc = (value) => typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(value) : value.replace(/"/g, '\\"');
+/** The production port glows: gold 4px, green 3px, blue 2px; `none` recedes. */
+function defaultPortCss(tier, selector) {
+    switch (tier) {
+        case 'top':
+            return `${selector} { fill: #f59e0b !important; stroke: #f59e0b !important; filter: drop-shadow(0 0 4px rgba(245,158,11,.4)) drop-shadow(0 0 2px rgba(245,158,11,.4)); }`;
+        case 'good':
+            return `${selector} { fill: #16a34a !important; stroke: #16a34a !important; filter: drop-shadow(0 0 3px rgba(22,163,74,.35)); }`;
+        case 'ok':
+            return `${selector} { fill: #2563eb !important; stroke: #2563eb !important; filter: drop-shadow(0 0 2px rgba(37,99,235,.3)); }`;
+        default:
+            return '';
+    }
+}
+/**
+ * Bind live join guidance to a diagram instance. Listens to the engine's
+ * connection lifecycle; while a drag is live, every kit-card row on every
+ * other table wears its tier class (and the best one its "★ BEST" chip), and
+ * the matching port glyphs glow via a generated stylesheet. Everything clears
+ * when the drag ends, however it ends.
+ */
+function bindJoinGuidance(api, options = {}) {
+    var _a, _b, _c, _d, _e;
+    ensureJoinGuidanceStyles(api.container.ownerDocument);
+    const chipText = (_a = options.chipText) !== null && _a !== void 0 ? _a : '★ BEST';
+    const portCss = (_b = options.portCss) !== null && _b !== void 0 ? _b : defaultPortCss;
+    const kitOf = (node) => {
+        var _a;
+        const raw = (_a = node === null || node === void 0 ? void 0 : node.getMetadata) === null || _a === void 0 ? void 0 : _a.call(node, 'kitEntity');
+        return raw && typeof raw === 'object' ? raw : null;
+    };
+    const defaultResolve = (portId, nodeId) => {
+        var _a, _b;
+        const model = api.getModel();
+        const nodes = nodeId
+            ? [model.getNode(nodeId)].filter((n) => !!n)
+            : ((_b = (_a = model.getNodes) === null || _a === void 0 ? void 0 : _a.call(model)) !== null && _b !== void 0 ? _b : []).filter((n) => { var _a; return !!((_a = n.getPort) === null || _a === void 0 ? void 0 : _a.call(n, portId)); });
+        for (const node of nodes) {
+            const kit = kitOf(node);
+            if (!(kit === null || kit === void 0 ? void 0 : kit.columns))
+                continue;
+            for (const column of kit.columns) {
+                if (portId === `${node.id}.${column.name}-in` ||
+                    portId === `${node.id}.${column.name}-out` ||
+                    portId.startsWith(`${node.id}__${column.name}__`)) {
+                    return { nodeId: node.id, column: column.name };
+                }
+            }
+        }
+        return null;
+    };
+    const resolvePort = (_c = options.resolvePort) !== null && _c !== void 0 ? _c : defaultResolve;
+    const active = new Map();
+    let portStyle = null;
+    const rowsOf = (nodeId) => {
+        const group = api.container.querySelector(`[data-node-id="${esc(nodeId)}"]`);
+        return group ? Array.from(group.querySelectorAll('.axk-row')) : [];
+    };
+    const clear = () => {
+        for (const cls of Object.values(TIER_CLASS)) {
+            for (const el of Array.from(api.container.querySelectorAll(`.${cls}`)))
+                el.classList.remove(cls);
+        }
+        for (const chip of Array.from(api.container.querySelectorAll(`.${CHIP_CLASS}`)))
+            chip.remove();
+        portStyle === null || portStyle === void 0 ? void 0 : portStyle.remove();
+        portStyle = null;
+        active.clear();
+    };
+    const portsForColumn = (node, column) => {
+        var _a, _b;
+        const ports = (_b = (_a = node.getPorts) === null || _a === void 0 ? void 0 : _a.call(node)) !== null && _b !== void 0 ? _b : [];
+        return ports
+            .map((p) => p.id)
+            .filter((id) => id === `${node.id}.${column}-in` ||
+            id === `${node.id}.${column}-out` ||
+            id.startsWith(`${node.id}__${column}__`));
+    };
+    const onStart = (data) => {
+        var _a, _b, _c;
+        clear();
+        const payload = data;
+        const sourcePort = payload === null || payload === void 0 ? void 0 : payload.sourcePort;
+        if (!sourcePort)
+            return;
+        const source = resolvePort(sourcePort.id, sourcePort.nodeId);
+        if (!source)
+            return;
+        const model = api.getModel();
+        const sourceNode = model.getNode(source.nodeId);
+        const sourceKit = kitOf(sourceNode);
+        const sourceColumn = (_a = sourceKit === null || sourceKit === void 0 ? void 0 : sourceKit.columns) === null || _a === void 0 ? void 0 : _a.find((c) => c.name === source.column);
+        if (!sourceColumn)
+            return;
+        const sourceEnd = { table: source.nodeId, column: sourceColumn };
+        // Every column of every OTHER kit table is a candidate, in node order.
+        const candidates = [];
+        for (const node of (_c = (_b = model.getNodes) === null || _b === void 0 ? void 0 : _b.call(model)) !== null && _c !== void 0 ? _c : []) {
+            if (node.id === source.nodeId)
+                continue; // the source table is NEVER tinted
+            const kit = kitOf(node);
+            if (!(kit === null || kit === void 0 ? void 0 : kit.columns))
+                continue;
+            kit.columns.forEach((column, rowIndex) => candidates.push({ node, rowIndex, column }));
+        }
+        if (candidates.length === 0)
+            return;
+        // The VALIDATOR outranks the score. A column can be the best textual
+        // match and still be un-connectable (its table pair already joined, or a
+        // custom validator refuses it) — the engine records those as
+        // invalidTargetPorts at drag start, and the renderer paints them red on
+        // hover. Tinting the same port gold would be the guidance lying about a
+        // target the drop will refuse (caught by the demo gate: the seeded
+        // customers⋈orders pair made customers.id both '★ BEST' and invalid).
+        const invalid = (() => {
+            var _a, _b, _c, _d, _e;
+            try {
+                const engine = (_a = api.getEngine) === null || _a === void 0 ? void 0 : _a.call(api);
+                const map = (_e = (_d = (_c = (_b = engine === null || engine === void 0 ? void 0 : engine.getConnectionStateManager) === null || _b === void 0 ? void 0 : _b.call(engine)) === null || _c === void 0 ? void 0 : _c.getState) === null || _d === void 0 ? void 0 : _d.call(_c)) === null || _e === void 0 ? void 0 : _e.invalidTargetPorts;
+                return new Set(map ? [...map.keys()] : []);
+            }
+            catch (_f) {
+                return new Set();
+            }
+        })();
+        const scores = candidates.map((c) => {
+            var _a, _b, _c;
+            const targetIn = `${c.node.id}.${c.column.name}-in`;
+            if (invalid.has(targetIn))
+                return 0;
+            const port = ((_c = (_b = (_a = c.node).getPort) === null || _b === void 0 ? void 0 : _b.call(_a, targetIn)) !== null && _c !== void 0 ? _c : null);
+            if ((port === null || port === void 0 ? void 0 : port.id) && invalid.has(port.id))
+                return 0;
+            return scoreMatch(sourceEnd, { table: c.node.id, column: c.column });
+        });
+        const tiers = assignTiers(scores);
+        const cssRules = [];
+        candidates.forEach((candidate, i) => {
+            var _a;
+            const tier = tiers[i];
+            const byRow = (_a = active.get(candidate.node.id)) !== null && _a !== void 0 ? _a : new Map();
+            byRow.set(candidate.rowIndex, tier);
+            active.set(candidate.node.id, byRow);
+            const row = rowsOf(candidate.node.id)[candidate.rowIndex];
+            if (row) {
+                row.classList.add(TIER_CLASS[tier]);
+                if (tier === 'top') {
+                    const chip = api.container.ownerDocument.createElement('span');
+                    chip.className = CHIP_CLASS;
+                    chip.textContent = chipText;
+                    row.appendChild(chip);
+                }
+            }
+            if (tier !== 'none') {
+                for (const portId of portsForColumn(candidate.node, candidate.column.name)) {
+                    const rule = portCss(tier, `[data-port-id="${esc(portId)}"]`);
+                    if (rule)
+                        cssRules.push(rule);
+                }
+            }
+        });
+        if (cssRules.length > 0) {
+            portStyle = api.container.ownerDocument.createElement('style');
+            portStyle.id = PORT_STYLE_ID;
+            portStyle.textContent = cssRules.join('\n');
+            api.container.ownerDocument.head.appendChild(portStyle);
+        }
+    };
+    const bus = (_e = (_d = api.getEngine) === null || _d === void 0 ? void 0 : _d.call(api)) === null || _e === void 0 ? void 0 : _e.eventBus;
+    const offs = [];
+    if (bus) {
+        offs.push(bus.on('connection:start', onStart));
+        offs.push(bus.on('connection:complete', clear));
+        offs.push(bus.on('connection:cancel', clear));
+        // The event-type constant spells it 'cancelled'; the state manager emits
+        // 'cancel'. Subscribe to both so a future spelling fix cannot leave tints on.
+        offs.push(bus.on('connection:cancelled', clear));
+    }
+    return {
+        activeTiers: () => {
+            const copy = new Map();
+            for (const [nodeId, byRow] of active)
+                copy.set(nodeId, new Map(byRow));
+            return copy;
+        },
+        dispose: () => {
+            for (const off of offs)
+                off();
+            clear();
+        },
+    };
+}
+//# sourceMappingURL=join-guidance.js.map