@grafloria/element 0.3.18 → 0.3.20

package/esm/src/lib/diagram-kit/handles.js

@@ -0,0 +1,312 @@
+import { __awaiter } from "tslib";
+import { updateEntity, updateClass } from './update';
+const deep = (v) => JSON.parse(JSON.stringify(v));
+// ---------------------------------------------------------------------------
+// Base
+// ---------------------------------------------------------------------------
+export class CardHandle {
+    constructor(api, id) {
+        this.api = api;
+        this.id = id;
+    }
+    /** The live node, or undefined once deleted. Handles never cache it. */
+    liveNode() {
+        return this.api.getModel().getNode(this.id);
+    }
+    get exists() {
+        return this.liveNode() !== undefined;
+    }
+    /** Escape hatch to the underlying NodeModel (typed loosely on purpose). */
+    get node() {
+        return this.liveNode();
+    }
+    get width() {
+        var _a, _b;
+        return (_b = (_a = this.liveNode()) === null || _a === void 0 ? void 0 : _a.size.width) !== null && _b !== void 0 ? _b : 0;
+    }
+    get height() {
+        var _a, _b;
+        return (_b = (_a = this.liveNode()) === null || _a === void 0 ? void 0 : _a.size.height) !== null && _b !== void 0 ? _b : 0;
+    }
+    select() {
+        var _a, _b, _c;
+        const model = this.api.getModel();
+        const node = model.getNode(this.id);
+        if (node)
+            (_a = model.selectNode) === null || _a === void 0 ? void 0 : _a.call(model, node);
+        (_c = (_b = this.api).renderNow) === null || _c === void 0 ? void 0 : _c.call(_b);
+    }
+    undo() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e;
+            yield ((_c = (_b = (_a = this.api).getEngine) === null || _b === void 0 ? void 0 : _b.call(_a)) === null || _c === void 0 ? void 0 : _c.undo());
+            (_e = (_d = this.api).renderNow) === null || _e === void 0 ? void 0 : _e.call(_d);
+        });
+    }
+    redo() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e;
+            yield ((_c = (_b = (_a = this.api).getEngine) === null || _b === void 0 ? void 0 : _b.call(_a)) === null || _c === void 0 ? void 0 : _c.redo());
+            (_e = (_d = this.api).renderNow) === null || _e === void 0 ? void 0 : _e.call(_d);
+        });
+    }
+    /**
+     * Row-selection events for THIS card only (the kit's `axk:row-select`,
+     * filtered). ER cards resolve the selection to a typed {@link ErField} when
+     * possible. Returns an unbind function.
+     */
+    onRowSelect(cb) {
+        const handler = (event) => {
+            var _a, _b, _c;
+            const selected = (_b = (_a = event.detail) === null || _a === void 0 ? void 0 : _a.selected) !== null && _b !== void 0 ? _b : null;
+            if (selected && selected.nodeId !== this.id)
+                return; // another card
+            if (!selected) {
+                cb({ field: null, selected: null });
+                return;
+            }
+            const field = this instanceof ErTable && selected.name !== undefined
+                ? ((_c = this.columns.get(selected.name)) !== null && _c !== void 0 ? _c : null)
+                : null;
+            cb({ field, selected });
+        };
+        this.api.container.addEventListener('axk:row-select', handler);
+        return () => this.api.container.removeEventListener('axk:row-select', handler);
+    }
+}
+// ---------------------------------------------------------------------------
+// ER
+// ---------------------------------------------------------------------------
+/** A column of an {@link ErTable} — itself just (table, name): stateless. */
+export class ErField {
+    constructor(table, columnName) {
+        this.table = table;
+        this.columnName = columnName;
+    }
+    col() {
+        return this.table.spec.columns.find((c) => c.name === this.columnName);
+    }
+    get exists() {
+        return this.col() !== undefined;
+    }
+    get name() {
+        return this.columnName;
+    }
+    get index() {
+        return this.table.spec.columns.findIndex((c) => c.name === this.columnName);
+    }
+    get type() {
+        var _a;
+        return (_a = this.col()) === null || _a === void 0 ? void 0 : _a.type;
+    }
+    get pk() {
+        var _a;
+        return ((_a = this.col()) === null || _a === void 0 ? void 0 : _a.pk) === true;
+    }
+    get fk() {
+        var _a;
+        return ((_a = this.col()) === null || _a === void 0 ? void 0 : _a.fk) === true;
+    }
+    /** Rename — the field port keeps its id, so attached edges stay glued. */
+    rename(name) {
+        return this.table.columns.renameAt(this.index, name);
+    }
+    setType(type) {
+        return this.table.columns.patchAt(this.index, { type });
+    }
+    setKeys(keys) {
+        return this.table.columns.patchAt(this.index, keys);
+    }
+    /** Remove this column (its ports and attached edges are dropped). */
+    remove() {
+        return this.table.columns.removeAt(this.index);
+    }
+}
+/** The columns collection of an {@link ErTable}. Iterable of {@link ErField}. */
+export class ErColumnList {
+    constructor(table) {
+        this.table = table;
+    }
+    cols() {
+        return this.table.spec.columns;
+    }
+    get length() {
+        return this.cols().length;
+    }
+    names() {
+        return this.cols().map((c) => c.name);
+    }
+    at(index) {
+        const c = this.cols()[index];
+        return c ? new ErField(this.table, c.name) : undefined;
+    }
+    get(name) {
+        return this.cols().some((c) => c.name === name) ? new ErField(this.table, name) : undefined;
+    }
+    [Symbol.iterator]() {
+        return this.cols()
+            .map((c) => new ErField(this.table, c.name))[Symbol.iterator]();
+    }
+    add(column, opts = {}) {
+        var _a;
+        const next = [...this.cols()];
+        next.splice((_a = opts.at) !== null && _a !== void 0 ? _a : next.length, 0, Object.assign({}, column));
+        return this.table.update({ columns: next });
+    }
+    removeAt(index) {
+        const next = this.cols().filter((_, i) => i !== index);
+        return this.table.update({ columns: next });
+    }
+    renameAt(index, name) {
+        return this.patchAt(index, { name });
+    }
+    patchAt(index, patch) {
+        const next = this.cols().map((c, i) => (i === index ? Object.assign(Object.assign({}, c), patch) : c));
+        return this.table.update({ columns: next });
+    }
+    move(from, to) {
+        const next = [...this.cols()];
+        const [c] = next.splice(from, 1);
+        next.splice(to, 0, c);
+        return this.table.update({ columns: next });
+    }
+}
+export class ErTable extends CardHandle {
+    constructor() {
+        super(...arguments);
+        this.columns = new ErColumnList(this);
+    }
+    /** A deep COPY of the stored entity spec — never a live reference. */
+    get spec() {
+        var _a, _b;
+        const raw = (_b = (_a = this.liveNode()) === null || _a === void 0 ? void 0 : _a.getMetadata) === null || _b === void 0 ? void 0 : _b.call(_a, 'kitEntity');
+        if (!raw)
+            throw new Error(`erTable('${this.id}'): the node is gone`);
+        return deep(raw);
+    }
+    get name() {
+        var _a;
+        return (_a = this.spec.name) !== null && _a !== void 0 ? _a : this.id;
+    }
+    rename(name) {
+        return this.update({ name });
+    }
+    resize(size) {
+        return this.update(size);
+    }
+    /** The raw delta path — everything above funnels through here. */
+    update(delta) {
+        return updateEntity(this.api, this.id, delta);
+    }
+}
+// ---------------------------------------------------------------------------
+// UML
+// ---------------------------------------------------------------------------
+/** attributes / methods of a {@link UmlClass} (members are plain strings). */
+export class UmlMemberList {
+    constructor(cls, kind) {
+        this.cls = cls;
+        this.kind = kind;
+    }
+    list() {
+        var _a;
+        return (_a = this.cls.spec[this.kind]) !== null && _a !== void 0 ? _a : [];
+    }
+    get length() {
+        return this.list().length;
+    }
+    at(index) {
+        return this.list()[index];
+    }
+    add(member, opts = {}) {
+        var _a;
+        const next = [...this.list()];
+        next.splice((_a = opts.at) !== null && _a !== void 0 ? _a : next.length, 0, member);
+        return this.cls.update({ [this.kind]: next });
+    }
+    removeAt(index) {
+        return this.cls.update({ [this.kind]: this.list().filter((_, i) => i !== index) });
+    }
+    renameAt(index, member) {
+        return this.cls.update({ [this.kind]: this.list().map((m, i) => (i === index ? member : m)) });
+    }
+}
+export class UmlClass extends CardHandle {
+    constructor() {
+        super(...arguments);
+        this.attributes = new UmlMemberList(this, 'attributes');
+        this.methods = new UmlMemberList(this, 'methods');
+    }
+    /** A deep COPY of the stored class spec — never a live reference. */
+    get spec() {
+        var _a, _b;
+        const raw = (_b = (_a = this.liveNode()) === null || _a === void 0 ? void 0 : _a.getMetadata) === null || _b === void 0 ? void 0 : _b.call(_a, 'kitClass');
+        if (!raw)
+            throw new Error(`umlClass('${this.id}'): the node is gone`);
+        return deep(raw);
+    }
+    get name() {
+        var _a;
+        return (_a = this.spec.name) !== null && _a !== void 0 ? _a : this.id;
+    }
+    get abstract() {
+        return this.spec.abstract === true;
+    }
+    get stereotype() {
+        return this.spec.stereotype;
+    }
+    rename(name) {
+        return this.update({ name });
+    }
+    resize(size) {
+        return this.update(size);
+    }
+    setAbstract(abstract) {
+        return this.update({ abstract });
+    }
+    setStereotype(stereotype) {
+        return this.update({ stereotype });
+    }
+    update(delta) {
+        return updateClass(this.api, this.id, delta);
+    }
+}
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+function requireKit(api, id, key, what) {
+    var _a;
+    const node = api.getModel().getNode(id);
+    if (!node)
+        throw new Error(`${what}('${id}'): no node with that id`);
+    if (!((_a = node.getMetadata) === null || _a === void 0 ? void 0 : _a.call(node, key))) {
+        throw new Error(`${what}('${id}'): that node is not an ${what === 'erTable' ? 'ER table' : 'UML class'} (missing metadata.${key})`);
+    }
+}
+/** Typed handle for a kit ER table. Throws for unknown ids / non-kit nodes. */
+export function erTable(api, id) {
+    requireKit(api, id, 'kitEntity', 'erTable');
+    return new ErTable(api, id);
+}
+/** Typed handle for a kit UML class. Throws for unknown ids / non-kit nodes. */
+export function umlClass(api, id) {
+    requireKit(api, id, 'kitClass', 'umlClass');
+    return new UmlClass(api, id);
+}
+/** Every kit ER table in the diagram, as handles. */
+export function erTables(api) {
+    var _a, _b;
+    const model = api.getModel();
+    return ((_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.getMetadata) === null || _a === void 0 ? void 0 : _a.call(n, 'kitEntity'); })
+        .map((n) => new ErTable(api, n.id));
+}
+/** Every kit UML class in the diagram, as handles. */
+export function umlClasses(api) {
+    var _a, _b;
+    const model = api.getModel();
+    return ((_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.getMetadata) === null || _a === void 0 ? void 0 : _a.call(n, 'kitClass'); })
+        .map((n) => new UmlClass(api, n.id));
+}
+//# sourceMappingURL=handles.js.map

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

@@ -0,0 +1,15 @@
+export { erDiagram, erRowCenterY, ER_ROW_H, ER_HEAD_H, } from './er';
+export { umlDiagram, } from './uml';
+export { ensureDiagramKitStyles, DIAGRAM_KIT_STYLE_ID } from './styles';
+export { bindRowInteractions } from './rows';
+export { updateEntity, updateClass, addColumnAt, removeColumnAt, renameColumnAt, } from './update';
+export { bindCardEditing } from './editing';
+export { matchColumns, rowIndexFromY } from './card';
+// The card CONTENT builders — shared with the stencil palette so a dropped
+// "Entity"/"Class" is the identical card erDiagram()/umlDiagram() produce.
+export { entityCardContent, entityAutoHeight, classCardContent, classAutoHeight } from './card';
+// 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).
+export { scoreMatch, matchTier, assignTiers, singularize, bindJoinGuidance, ensureJoinGuidanceStyles, JOIN_GUIDANCE_STYLE_ID, } from './join-guidance';
+export { erTable, umlClass, erTables, umlClasses, CardHandle, ErTable, ErField, ErColumnList, UmlClass, UmlMemberList, } from './handles';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,322 @@
+/**
+ * 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.
+ */
+/** Naive English singular — enough for schema names (orders, categories, statuses). */
+export 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".
+ */
+export 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`). */
+export 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.
+ */
+export 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';
+export const 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. */
+export function ensureJoinGuidanceStyles(doc = typeof document !== 'undefined' ? document : undefined) {
+    if (!doc)
+        return;
+    if (doc.getElementById(JOIN_GUIDANCE_STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = 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.
+ */
+export 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