@grafloria/element 0.3.19 → 0.3.20

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

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

@@ -0,0 +1,144 @@
+/**
+ * Row interactions — "select a column / field" on kit cards (P1 of the
+ * ER/UML editing track).
+ *
+ * Kit cards are `interactive: true` (their rows are real DOM targets — the
+ * binder's node click/drag resolution is geometric, so dragging and selecting
+ * the TABLE keeps working; proven live before this was built). This module is
+ * the runtime the kit's `finalize(api)` binds once per diagram:
+ *
+ *  - click a row → it becomes THE selected row (one per diagram), painted with
+ *    `.axk-row-selected`; click again or click anywhere else → deselected;
+ *  - every row click dispatches `axk:row-click` on the container, and every
+ *    selection CHANGE dispatches `axk:row-select` — both bubbling
+ *    CustomEvents, matching the element package's "DOM events out" contract;
+ *  - the selected row survives card re-renders: the renderer keys the
+ *    foreignObject by content hash, so an html edit swaps the subtree and
+ *    drops the class — a MutationObserver re-applies it by (nodeId, rowIndex);
+ *  - selection is EPHEMERAL view state, exactly like node selection: never
+ *    serialized, never in the op log, not undoable.
+ *
+ * Row identity: `rowIndex` is the position among the card's rows (ER columns,
+ * or UML members across both compartments); `name` resolves from the spec the
+ * kit stored in node metadata (`kitEntity` / `kitClass`), falling back to the
+ * row's text.
+ */
+const ROW_SELECTOR = '.axk-row, .axk-member';
+const SELECTED_CLASS = 'axk-row-selected';
+/** One binding per container — rebinding disposes the previous one. */
+const bindings = new WeakMap();
+function rowsOfNode(container, nodeId) {
+    const esc = (window.CSS && CSS.escape) ? CSS.escape(nodeId) : nodeId.replace(/"/g, '\\"');
+    const group = container.querySelector(`[data-node-id="${esc}"]`);
+    return group ? Array.from(group.querySelectorAll(ROW_SELECTOR)) : [];
+}
+function resolveRef(container, api, rowEl) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+    const group = rowEl.closest('[data-node-id]');
+    if (!group)
+        return null;
+    const nodeId = group.getAttribute('data-node-id');
+    const rows = Array.from(group.querySelectorAll(ROW_SELECTOR));
+    const rowIndex = rows.indexOf(rowEl);
+    if (rowIndex === -1)
+        return null;
+    const kind = rowEl.classList.contains('axk-member') ? 'uml' : 'er';
+    const node = (_c = (_a = api.getModel) === null || _a === void 0 ? void 0 : (_b = _a.call(api)).getNode) === null || _c === void 0 ? void 0 : _c.call(_b, nodeId);
+    const meta = (key) => { var _a; return (_a = node === null || node === void 0 ? void 0 : node.getMetadata) === null || _a === void 0 ? void 0 : _a.call(node, key); };
+    if (kind === 'er') {
+        const entity = meta('kitEntity');
+        const name = (_h = (_f = (_e = (_d = entity === null || entity === void 0 ? void 0 : entity.columns) === null || _d === void 0 ? void 0 : _d[rowIndex]) === null || _e === void 0 ? void 0 : _e.name) !== null && _f !== void 0 ? _f : (_g = rowEl.querySelector('.axk-col')) === null || _g === void 0 ? void 0 : _g.textContent) !== null && _h !== void 0 ? _h : undefined;
+        return { nodeId, rowIndex, name: name !== null && name !== void 0 ? name : undefined, kind };
+    }
+    const cls = meta('kitClass');
+    const attrCount = (_k = (_j = cls === null || cls === void 0 ? void 0 : cls.attributes) === null || _j === void 0 ? void 0 : _j.length) !== null && _k !== void 0 ? _k : countFirstCompartment(rowEl);
+    const section = rowIndex < attrCount ? 'attributes' : 'methods';
+    const name = (_q = (_o = (section === 'attributes' ? (_l = cls === null || cls === void 0 ? void 0 : cls.attributes) === null || _l === void 0 ? void 0 : _l[rowIndex] : (_m = cls === null || cls === void 0 ? void 0 : cls.methods) === null || _m === void 0 ? void 0 : _m[rowIndex - attrCount])) !== null && _o !== void 0 ? _o : (_p = rowEl.textContent) === null || _p === void 0 ? void 0 : _p.trim()) !== null && _q !== void 0 ? _q : undefined;
+    return { nodeId, rowIndex, name, kind, section };
+}
+/** Without spec metadata, the first compartment's member count splits sections. */
+function countFirstCompartment(rowEl) {
+    const card = rowEl.closest('.axk-uml');
+    const firstComp = card === null || card === void 0 ? void 0 : card.querySelector('.axk-uml-comp');
+    return firstComp ? firstComp.querySelectorAll('.axk-member').length : Number.MAX_SAFE_INTEGER;
+}
+export function bindRowInteractions(api) {
+    var _a;
+    const container = api.container;
+    (_a = bindings.get(container)) === null || _a === void 0 ? void 0 : _a.dispose();
+    let selected = null;
+    const paint = () => {
+        var _a;
+        for (const el of Array.from(container.querySelectorAll(`.${SELECTED_CLASS}`))) {
+            el.classList.remove(SELECTED_CLASS);
+        }
+        if (selected)
+            (_a = rowsOfNode(container, selected.nodeId)[selected.rowIndex]) === null || _a === void 0 ? void 0 : _a.classList.add(SELECTED_CLASS);
+    };
+    const emitSelect = () => {
+        container.dispatchEvent(new CustomEvent('axk:row-select', { bubbles: true, detail: { selected } }));
+    };
+    const setSelected = (next) => {
+        const same = (next === null && selected === null) ||
+            (next !== null && selected !== null && next.nodeId === selected.nodeId && next.rowIndex === selected.rowIndex);
+        if (same)
+            return;
+        selected = next;
+        paint();
+        emitSelect();
+    };
+    const onClick = (event) => {
+        var _a;
+        const target = event.target instanceof Element ? event.target : null;
+        const rowEl = (_a = target === null || target === void 0 ? void 0 : target.closest) === null || _a === void 0 ? void 0 : _a.call(target, ROW_SELECTOR);
+        if (!rowEl || !container.contains(rowEl)) {
+            setSelected(null);
+            return;
+        }
+        const ref = resolveRef(container, api, rowEl);
+        if (!ref)
+            return;
+        container.dispatchEvent(new CustomEvent('axk:row-click', { bubbles: true, detail: Object.assign({}, ref) }));
+        const isReclick = selected && selected.nodeId === ref.nodeId && selected.rowIndex === ref.rowIndex;
+        setSelected(isReclick ? null : ref);
+    };
+    // Card re-renders replace the foreignObject subtree (content-hash keyed) and
+    // lose the class — re-apply whenever the selected row's paint went missing.
+    const observer = new MutationObserver(() => {
+        if (!selected)
+            return;
+        const el = rowsOfNode(container, selected.nodeId)[selected.rowIndex];
+        if (el && !el.classList.contains(SELECTED_CLASS))
+            paint();
+        else if (!el) {
+            // The row (or its node) is gone — the selection dies with it.
+            setSelected(null);
+        }
+    });
+    container.addEventListener('click', onClick);
+    observer.observe(container, { childList: true, subtree: true });
+    const handle = {
+        getSelected: () => (selected ? Object.assign({}, selected) : null),
+        select: (ref) => {
+            if (ref === null) {
+                setSelected(null);
+                return;
+            }
+            const el = rowsOfNode(container, ref.nodeId)[ref.rowIndex];
+            if (!el)
+                return;
+            const resolved = resolveRef(container, api, el);
+            if (resolved)
+                setSelected(resolved);
+        },
+        dispose: () => {
+            container.removeEventListener('click', onClick);
+            observer.disconnect();
+            if (bindings.get(container) === handle)
+                bindings.delete(container);
+        },
+    };
+    bindings.set(container, handle);
+    return handle;
+}
+//# sourceMappingURL=rows.js.map

package/{src/lib/diagram-kit/styles.ts → esm/src/lib/diagram-kit/styles.js}

@@ -13,9 +13,7 @@
  *    OUTSIDE the node) reads as a second floating box around a bordered card —
  *    the kit hides it and rings the card itself instead.
  */
-
 export const DIAGRAM_KIT_STYLE_ID = 'grafloria-diagram-kit-styles';
-
 const CSS = `
 /* ===== ER entity (table) cards ===== */
 .axk-entity { font: 12px/1.5 system-ui, sans-serif; border: 1px solid #64748b;
@@ -106,13 +104,15 @@ g.node-group[data-selected="true"]:has(.axk-uml) rect.diagram-node {
   .axk-member { color: #e2e8f0; }
 }
 `;
-
 /** Inject the kit stylesheet once. Safe to call repeatedly and in SSR. */
-export function ensureDiagramKitStyles(doc: Document | undefined = typeof document !== 'undefined' ? document : undefined): void {
-  if (!doc) return;
-  if (doc.getElementById(DIAGRAM_KIT_STYLE_ID)) return;
-  const style = doc.createElement('style');
-  style.id = DIAGRAM_KIT_STYLE_ID;
-  style.textContent = CSS;
-  doc.head.appendChild(style);
+export function ensureDiagramKitStyles(doc = typeof document !== 'undefined' ? document : undefined) {
+    if (!doc)
+        return;
+    if (doc.getElementById(DIAGRAM_KIT_STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = DIAGRAM_KIT_STYLE_ID;
+    style.textContent = CSS;
+    doc.head.appendChild(style);
 }
+//# sourceMappingURL=styles.js.map

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

@@ -0,0 +1,135 @@
+/**
+ * UML class-diagram kit — typed builders for the full relationship vocabulary.
+ *
+ * The packaged form of demos/diagrams/class-uml.html + uml-relationships.html:
+ * three-compartment class cards («stereotype», name, attributes, methods) and
+ * every standard relationship with its real notation:
+ *
+ *   inheritance          ── solid,  hollow triangle at the parent
+ *   realization          ┄┄ dashed, hollow triangle at the interface
+ *   association          ── plain line (multiplicity chips optional)
+ *   directed-association ── open arrow at the target
+ *   aggregation          ── hollow diamond at the whole (source)
+ *   composition          ── FILLED diamond at the whole (source)
+ *   dependency           ┄┄ dashed, open arrow («uses»)
+ *
+ * ```ts
+ * const spec = umlDiagram({
+ *   classes: [{ id: 'Shape', abstract: true, attributes: ['# x: float'], methods: ['+ area(): float'] }],
+ *   relationships: [{ from: 'Circle', to: 'Shape', kind: 'inheritance' }],
+ * });
+ * const api = render(spec, container);
+ * spec.finalize(api); // attaches multiplicity chips (needs the live model)
+ * ```
+ */
+import { ensureDiagramKitStyles } from './styles';
+import { bindRowInteractions } from './rows';
+import { classCardContent, classAutoHeight } from './card';
+import { bindCardEditing } from './editing';
+const DEFAULT_WIDTH = 200;
+const STROKE = '#475569';
+const DASH = '6,4';
+/**
+ * The notation table. Every kind sets arrowHead EXPLICITLY — a plain line must
+ * carry `arrowHead: none`, or the renderer paints its default arrow (the
+ * stray-arrowhead bug the demos hit live).
+ */
+function edgeStyleFor(kind) {
+    const none = { type: 'none', size: 0, filled: false };
+    switch (kind) {
+        case 'inheritance':
+            return { stroke: STROKE, strokeWidth: 1.5, arrowHead: { type: 'generalization', size: 16, filled: false }, arrowTail: none };
+        case 'realization':
+            return { stroke: STROKE, strokeWidth: 1.5, strokeDasharray: DASH, arrowHead: { type: 'generalization', size: 16, filled: false }, arrowTail: none };
+        case 'association':
+            return { stroke: STROKE, strokeWidth: 1.5, arrowHead: none, arrowTail: none };
+        case 'directed-association':
+            return { stroke: STROKE, strokeWidth: 1.5, arrowHead: { type: 'open-arrow', size: 12, filled: false }, arrowTail: none };
+        case 'aggregation':
+            return { stroke: STROKE, strokeWidth: 1.5, arrowHead: none, arrowTail: { type: 'hollow-diamond', size: 14, filled: false } };
+        case 'composition':
+            return { stroke: STROKE, strokeWidth: 1.5, arrowHead: none, arrowTail: { type: 'filled-diamond', size: 14, filled: true } };
+        case 'dependency':
+            return { stroke: STROKE, strokeWidth: 1.5, strokeDasharray: DASH, arrowHead: { type: 'open-arrow', size: 12, filled: false }, arrowTail: none };
+    }
+}
+/** Multiplicity chip, positioned near an edge end. */
+const chip = (text, slot) => ({
+    text,
+    slot,
+    offset: { x: 0, y: -7 },
+    style: { fontSize: 11, fontWeight: '600', color: '#0f172a', background: '#ffffffdd', padding: 1, borderRadius: 2 },
+});
+/**
+ * Build a render() spec for a UML class diagram. Call `spec.finalize(api)`
+ * after render() — multiplicity chips are positioned labels, which only the
+ * live model's `link.addLabel` can express.
+ */
+export function umlDiagram(options) {
+    var _a;
+    ensureDiagramKitStyles();
+    const editable = options.editable === true;
+    const nodes = options.classes.map((cls, i) => {
+        var _a, _b;
+        return {
+            id: cls.id,
+            position: (_a = cls.position) !== null && _a !== void 0 ? _a : { x: 80 + (i % 3) * 320, y: 60 + Math.floor(i / 3) * 260 },
+            size: { width: (_b = cls.width) !== null && _b !== void 0 ? _b : DEFAULT_WIDTH, height: classAutoHeight(cls, editable) },
+            // interactive: members are real DOM targets (hover, row selection, inline
+            // editing); node drag/select stay geometric in the binder.
+            metadata: Object.assign({ html: { content: classCardContent(cls, editable), interactive: true }, kitClass: cls, kitEditable: editable }, (options.rowSelection === false ? { kitRowSelection: false } : {})),
+            shape: { type: 'rect', fill: 'none', stroke: 'none' },
+            style: { fill: 'transparent', stroke: 'transparent', strokeWidth: 0 },
+        };
+    });
+    const rels = (_a = options.relationships) !== null && _a !== void 0 ? _a : [];
+    const edges = rels.map((rel, i) => {
+        var _a, _b;
+        return (Object.assign(Object.assign(Object.assign({ id: (_a = rel.id) !== null && _a !== void 0 ? _a : `uml-rel-${i + 1}`, source: rel.from, target: rel.to, label: rel.label, type: 'orthogonal' }, (rel.fromSide ? { sourceHandle: rel.fromSide } : {})), (rel.toSide ? { targetHandle: rel.toSide } : {})), { style: edgeStyleFor((_b = rel.kind) !== null && _b !== void 0 ? _b : 'association') }));
+    });
+    // finalize is idempotent per api: render() auto-runs it, and a demo may also
+    // call it — chips must not be added twice.
+    const finalized = new WeakSet();
+    const finalize = (api) => {
+        var _a, _b, _c, _d, _e, _f;
+        const a0 = api;
+        // Own card ring only — suppress the node resize handles on the live model
+        // (the render-input path does not honour a spec-level `behavior`).
+        const m0 = (_a = a0 === null || a0 === void 0 ? void 0 : a0.getModel) === null || _a === void 0 ? void 0 : _a.call(a0);
+        if (m0)
+            for (const cls of options.classes)
+                (_d = (_c = (_b = m0.getNode) === null || _b === void 0 ? void 0 : _b.call(m0, cls.id)) === null || _c === void 0 ? void 0 : _c.setBehavior) === null || _d === void 0 ? void 0 : _d.call(_c, { resizable: false });
+        if (options.rowSelection !== false) {
+            const a = api;
+            // bindRowInteractions disposes any prior binding for the container, so it
+            // is safe to run twice.
+            if (a === null || a === void 0 ? void 0 : a.container)
+                bindRowInteractions(a);
+        }
+        if (editable && (a0 === null || a0 === void 0 ? void 0 : a0.container))
+            bindCardEditing(a0);
+        if (api && typeof api === 'object') {
+            if (finalized.has(api))
+                return;
+            finalized.add(api);
+        }
+        const model = (_e = api === null || api === void 0 ? void 0 : api.getModel) === null || _e === void 0 ? void 0 : _e.call(api);
+        if (!model)
+            return;
+        let added = false;
+        rels.forEach((rel, i) => {
+            if (!rel.multiplicity)
+                return;
+            const link = model.getLink(edges[i].id);
+            if (!link)
+                return;
+            link.addLabel(chip(rel.multiplicity[0], 'start'));
+            link.addLabel(chip(rel.multiplicity[1], 'end'));
+            added = true;
+        });
+        if (added)
+            (_f = api === null || api === void 0 ? void 0 : api.renderNow) === null || _f === void 0 ? void 0 : _f.call(api);
+    };
+    return { nodes, edges, finalize };
+}
+//# sourceMappingURL=uml.js.map