@grafloria/element 0.3.17 → 0.3.19

package/src/lib/diagram-kit/handles.ts

@@ -0,0 +1,375 @@
+/**
+ * Typed façade handles — Option B of the domain-API decision (2026-07-19):
+ * the clean OO surface over the data-first kit, with NO engine changes.
+ *
+ * ```ts
+ * const t = erTable(api, 'ORDERS');
+ * await t.rename('Sales Orders');
+ * await t.columns.add({ name: 'status', type: 'varchar' }, { at: 2 });
+ * await t.columns.get('customer_id')!.rename('cust_id');  // ports stay glued
+ * t.onRowSelect(({ field }) => panel.show(field));
+ * await t.undo();
+ * ```
+ *
+ * THE DESIGN INVARIANT: a handle is STATELESS — nothing but `(api, id)`. Every
+ * getter re-reads the live model (`metadata.kitEntity` / `kitClass`), so a
+ * handle can never go stale across re-renders, undo, collab, or edits made
+ * behind its back. Every mutation funnels through `updateEntity`/`updateClass`,
+ * so one-step undo and field-port reconciliation are inherited, not
+ * re-implemented. Inheritance lives HERE — `CardHandle → ErTable / UmlClass` —
+ * where it is safe, never on the stored NodeModel (which the engine
+ * reconstructs from data on undo/paste/collab; see the decision doc).
+ */
+import type { ErColumn, ErEntitySpec } from './er';
+import type { UmlClassSpec } from './uml';
+import { updateEntity, updateClass } from './update';
+import type { RowRef } from './rows';
+
+/** The slice of DiagramInstance the handles need (same shape update.ts uses). */
+export interface HandleApi {
+  container: HTMLElement;
+  getModel(): {
+    getNode(id: string):
+      | {
+          getMetadata?(key: string): unknown;
+          size: { width: number; height: number };
+          state?: { selected?: boolean };
+        }
+      | undefined;
+    selectNode?(node: unknown): void;
+  };
+  getEngine?(): { undo(): Promise<void> | void; redo(): Promise<void> | void } | undefined;
+  renderNow?(): void;
+}
+
+const deep = <T>(v: T): T => JSON.parse(JSON.stringify(v)) as T;
+
+// ---------------------------------------------------------------------------
+// Base
+// ---------------------------------------------------------------------------
+
+export abstract class CardHandle {
+  constructor(
+    protected readonly api: HandleApi,
+    readonly id: string
+  ) {}
+
+  /** The live node, or undefined once deleted. Handles never cache it. */
+  protected liveNode() {
+    return this.api.getModel().getNode(this.id);
+  }
+
+  get exists(): boolean {
+    return this.liveNode() !== undefined;
+  }
+
+  /** Escape hatch to the underlying NodeModel (typed loosely on purpose). */
+  get node(): unknown {
+    return this.liveNode();
+  }
+
+  get width(): number {
+    return this.liveNode()?.size.width ?? 0;
+  }
+
+  get height(): number {
+    return this.liveNode()?.size.height ?? 0;
+  }
+
+  abstract get name(): string;
+  /** Rename the card title — one undoable step. */
+  abstract rename(name: string): Promise<boolean>;
+  /** Resize the card — one undoable step (kit body scrolls when capped). */
+  abstract resize(size: { width?: number; height?: number }): Promise<boolean>;
+
+  select(): void {
+    const model = this.api.getModel();
+    const node = model.getNode(this.id);
+    if (node) model.selectNode?.(node);
+    this.api.renderNow?.();
+  }
+
+  async undo(): Promise<void> {
+    await this.api.getEngine?.()?.undo();
+    this.api.renderNow?.();
+  }
+
+  async redo(): Promise<void> {
+    await this.api.getEngine?.()?.redo();
+    this.api.renderNow?.();
+  }
+
+  /**
+   * 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: (e: { field: ErField | null; selected: RowRef | null }) => void
+  ): () => void {
+    const handler = (event: Event): void => {
+      const selected = (event as CustomEvent<{ selected: RowRef | null }>).detail?.selected ?? 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
+          ? (this.columns.get(selected.name) ?? 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(
+    readonly table: ErTable,
+    private readonly columnName: string
+  ) {}
+
+  private col(): ErColumn | undefined {
+    return this.table.spec.columns.find((c) => c.name === this.columnName);
+  }
+
+  get exists(): boolean {
+    return this.col() !== undefined;
+  }
+  get name(): string {
+    return this.columnName;
+  }
+  get index(): number {
+    return this.table.spec.columns.findIndex((c) => c.name === this.columnName);
+  }
+  get type(): string | undefined {
+    return this.col()?.type;
+  }
+  get pk(): boolean {
+    return this.col()?.pk === true;
+  }
+  get fk(): boolean {
+    return this.col()?.fk === true;
+  }
+
+  /** Rename — the field port keeps its id, so attached edges stay glued. */
+  rename(name: string): Promise<boolean> {
+    return this.table.columns.renameAt(this.index, name);
+  }
+
+  setType(type: string): Promise<boolean> {
+    return this.table.columns.patchAt(this.index, { type });
+  }
+
+  setKeys(keys: { pk?: boolean; fk?: boolean }): Promise<boolean> {
+    return this.table.columns.patchAt(this.index, keys);
+  }
+
+  /** Remove this column (its ports and attached edges are dropped). */
+  remove(): Promise<boolean> {
+    return this.table.columns.removeAt(this.index);
+  }
+}
+
+/** The columns collection of an {@link ErTable}. Iterable of {@link ErField}. */
+export class ErColumnList implements Iterable<ErField> {
+  constructor(private readonly table: ErTable) {}
+
+  private cols(): ErColumn[] {
+    return this.table.spec.columns;
+  }
+
+  get length(): number {
+    return this.cols().length;
+  }
+  names(): string[] {
+    return this.cols().map((c) => c.name);
+  }
+  at(index: number): ErField | undefined {
+    const c = this.cols()[index];
+    return c ? new ErField(this.table, c.name) : undefined;
+  }
+  get(name: string): ErField | undefined {
+    return this.cols().some((c) => c.name === name) ? new ErField(this.table, name) : undefined;
+  }
+  [Symbol.iterator](): Iterator<ErField> {
+    return this.cols()
+      .map((c) => new ErField(this.table, c.name))
+      [Symbol.iterator]();
+  }
+
+  add(column: ErColumn, opts: { at?: number } = {}): Promise<boolean> {
+    const next = [...this.cols()];
+    next.splice(opts.at ?? next.length, 0, { ...column });
+    return this.table.update({ columns: next });
+  }
+
+  removeAt(index: number): Promise<boolean> {
+    const next = this.cols().filter((_, i) => i !== index);
+    return this.table.update({ columns: next });
+  }
+
+  renameAt(index: number, name: string): Promise<boolean> {
+    return this.patchAt(index, { name });
+  }
+
+  patchAt(index: number, patch: Partial<ErColumn>): Promise<boolean> {
+    const next = this.cols().map((c, i) => (i === index ? { ...c, ...patch } : c));
+    return this.table.update({ columns: next });
+  }
+
+  move(from: number, to: number): Promise<boolean> {
+    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 {
+  readonly columns = new ErColumnList(this);
+
+  /** A deep COPY of the stored entity spec — never a live reference. */
+  get spec(): ErEntitySpec {
+    const raw = this.liveNode()?.getMetadata?.('kitEntity') as ErEntitySpec | undefined;
+    if (!raw) throw new Error(`erTable('${this.id}'): the node is gone`);
+    return deep(raw);
+  }
+
+  get name(): string {
+    return this.spec.name ?? this.id;
+  }
+
+  rename(name: string): Promise<boolean> {
+    return this.update({ name });
+  }
+
+  resize(size: { width?: number; height?: number }): Promise<boolean> {
+    return this.update(size);
+  }
+
+  /** The raw delta path — everything above funnels through here. */
+  update(delta: Parameters<typeof updateEntity>[2]): Promise<boolean> {
+    return updateEntity(this.api as never, this.id, delta);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// UML
+// ---------------------------------------------------------------------------
+
+/** attributes / methods of a {@link UmlClass} (members are plain strings). */
+export class UmlMemberList {
+  constructor(
+    private readonly cls: UmlClass,
+    private readonly kind: 'attributes' | 'methods'
+  ) {}
+
+  list(): string[] {
+    return this.cls.spec[this.kind] ?? [];
+  }
+  get length(): number {
+    return this.list().length;
+  }
+  at(index: number): string | undefined {
+    return this.list()[index];
+  }
+
+  add(member: string, opts: { at?: number } = {}): Promise<boolean> {
+    const next = [...this.list()];
+    next.splice(opts.at ?? next.length, 0, member);
+    return this.cls.update({ [this.kind]: next });
+  }
+  removeAt(index: number): Promise<boolean> {
+    return this.cls.update({ [this.kind]: this.list().filter((_, i) => i !== index) });
+  }
+  renameAt(index: number, member: string): Promise<boolean> {
+    return this.cls.update({ [this.kind]: this.list().map((m, i) => (i === index ? member : m)) });
+  }
+}
+
+export class UmlClass extends CardHandle {
+  readonly attributes = new UmlMemberList(this, 'attributes');
+  readonly methods = new UmlMemberList(this, 'methods');
+
+  /** A deep COPY of the stored class spec — never a live reference. */
+  get spec(): UmlClassSpec {
+    const raw = this.liveNode()?.getMetadata?.('kitClass') as UmlClassSpec | undefined;
+    if (!raw) throw new Error(`umlClass('${this.id}'): the node is gone`);
+    return deep(raw);
+  }
+
+  get name(): string {
+    return this.spec.name ?? this.id;
+  }
+  get abstract(): boolean {
+    return this.spec.abstract === true;
+  }
+  get stereotype(): string | undefined {
+    return this.spec.stereotype;
+  }
+
+  rename(name: string): Promise<boolean> {
+    return this.update({ name });
+  }
+  resize(size: { width?: number; height?: number }): Promise<boolean> {
+    return this.update(size);
+  }
+  setAbstract(abstract: boolean): Promise<boolean> {
+    return this.update({ abstract });
+  }
+  setStereotype(stereotype: string | undefined): Promise<boolean> {
+    return this.update({ stereotype });
+  }
+
+  update(delta: Parameters<typeof updateClass>[2]): Promise<boolean> {
+    return updateClass(this.api as never, this.id, delta);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+
+function requireKit(api: HandleApi, id: string, key: 'kitEntity' | 'kitClass', what: string): void {
+  const node = api.getModel().getNode(id);
+  if (!node) throw new Error(`${what}('${id}'): no node with that id`);
+  if (!node.getMetadata?.(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: HandleApi, id: string): ErTable {
+  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: HandleApi, id: string): UmlClass {
+  requireKit(api, id, 'kitClass', 'umlClass');
+  return new UmlClass(api, id);
+}
+
+/** Every kit ER table in the diagram, as handles. */
+export function erTables(api: HandleApi): ErTable[] {
+  const model = api.getModel() as unknown as { getNodes?: () => Array<{ id: string; getMetadata?: (k: string) => unknown }> };
+  return (model.getNodes?.() ?? [])
+    .filter((n) => n.getMetadata?.('kitEntity'))
+    .map((n) => new ErTable(api, n.id));
+}
+
+/** Every kit UML class in the diagram, as handles. */
+export function umlClasses(api: HandleApi): UmlClass[] {
+  const model = api.getModel() as unknown as { getNodes?: () => Array<{ id: string; getMetadata?: (k: string) => unknown }> };
+  return (model.getNodes?.() ?? [])
+    .filter((n) => n.getMetadata?.('kitClass'))
+    .map((n) => new UmlClass(api, n.id));
+}

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/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../libs/element/src/lib/diagram-kit/index.ts"],"names":[],"mappings":";;;AAAA,2BAWc;AAVZ,+FAAA,SAAS,OAAA;AACT,kGAAA,YAAY,OAAA;AACZ,8FAAA,QAAQ,OAAA;AACR,+FAAA,SAAS,OAAA;AAQX,6BAOe;AANb,iGAAA,UAAU,OAAA;AAOZ,mCAAwE;AAA/D,gHAAA,sBAAsB,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AACrD,+BAAsF;AAA7E,2GAAA,mBAAmB,OAAA;AAC5B,mCAQkB;AAPhB,sGAAA,YAAY,OAAA;AACZ,qGAAA,WAAW,OAAA;AACX,qGAAA,WAAW,OAAA;AACX,wGAAA,cAAc,OAAA;AACd,wGAAA,cAAc,OAAA;AAIhB,qCAAoE;AAA3D,0GAAA,eAAe,OAAA;AACxB,+BAAqD;AAA5C,oGAAA,YAAY,OAAA;AAAE,qGAAA,aAAa,OAAA;AACpC,2EAA2E;AAC3E,2EAA2E;AAC3E,+BAAgG;AAAvF,yGAAA,iBAAiB,OAAA;AAAE,wGAAA,gBAAgB,OAAA;AAAE,wGAAA,gBAAgB,OAAA;AAAE,uGAAA,eAAe,OAAA;AAC/E,qCAYmB;AAXjB,kGAAA,OAAO,OAAA;AACP,mGAAA,QAAQ,OAAA;AACR,mGAAA,QAAQ,OAAA;AACR,qGAAA,UAAU,OAAA;AACV,qGAAA,UAAU,OAAA;AACV,kGAAA,OAAO,OAAA;AACP,kGAAA,OAAO,OAAA;AACP,uGAAA,YAAY,OAAA;AACZ,mGAAA,QAAQ,OAAA;AACR,wGAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,2BAWc;AAVZ,+FAAA,SAAS,OAAA;AACT,kGAAA,YAAY,OAAA;AACZ,8FAAA,QAAQ,OAAA;AACR,+FAAA,SAAS,OAAA;AAQX,6BAOe;AANb,iGAAA,UAAU,OAAA;AAOZ,mCAAwE;AAA/D,gHAAA,sBAAsB,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AACrD,+BAAsF;AAA7E,2GAAA,mBAAmB,OAAA;AAC5B,mCAQkB;AAPhB,sGAAA,YAAY,OAAA;AACZ,qGAAA,WAAW,OAAA;AACX,qGAAA,WAAW,OAAA;AACX,wGAAA,cAAc,OAAA;AACd,wGAAA,cAAc,OAAA;AAIhB,qCAAoE;AAA3D,0GAAA,eAAe,OAAA;AACxB,+BAAqD;AAA5C,oGAAA,YAAY,OAAA;AAAE,qGAAA,aAAa,OAAA;AACpC,2EAA2E;AAC3E,2EAA2E;AAC3E,+BAAgG;AAAvF,yGAAA,iBAAiB,OAAA;AAAE,wGAAA,gBAAgB,OAAA;AAAE,wGAAA,gBAAgB,OAAA;AAAE,uGAAA,eAAe,OAAA;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,iDAcyB;AAbvB,2GAAA,UAAU,OAAA;AACV,0GAAA,SAAS,OAAA;AACT,4GAAA,WAAW,OAAA;AACX,4GAAA,WAAW,OAAA;AACX,iHAAA,gBAAgB,OAAA;AAChB,yHAAA,wBAAwB,OAAA;AACxB,uHAAA,sBAAsB,OAAA;AAQxB,qCAYmB;AAXjB,kGAAA,OAAO,OAAA;AACP,mGAAA,QAAQ,OAAA;AACR,mGAAA,QAAQ,OAAA;AACR,qGAAA,UAAU,OAAA;AACV,qGAAA,UAAU,OAAA;AACV,kGAAA,OAAO,OAAA;AACP,kGAAA,OAAO,OAAA;AACP,uGAAA,YAAY,OAAA;AACZ,mGAAA,QAAQ,OAAA;AACR,wGAAA,aAAa,OAAA"}

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

@@ -0,0 +1,66 @@
+export {
+  erDiagram,
+  erRowCenterY,
+  ER_ROW_H,
+  ER_HEAD_H,
+  type ErColumn,
+  type ErEntitySpec,
+  type ErRelationshipSpec,
+  type ErCardinality,
+  type ErSide,
+  type ErDiagramOptions,
+} from './er';
+export {
+  umlDiagram,
+  type UmlClassSpec,
+  type UmlRelationshipSpec,
+  type UmlRelationKind,
+  type UmlSide,
+  type UmlDiagramOptions,
+} from './uml';
+export { ensureDiagramKitStyles, DIAGRAM_KIT_STYLE_ID } from './styles';
+export { bindRowInteractions, type RowRef, type RowInteractionsHandle } from './rows';
+export {
+  updateEntity,
+  updateClass,
+  addColumnAt,
+  removeColumnAt,
+  renameColumnAt,
+  type ErEntityDelta,
+  type UmlClassDelta,
+} from './update';
+export { bindCardEditing, type CardEditingHandle } 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,
+  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/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 {};