@grafloria/element 0.1.0

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

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ER_HEAD_H = exports.ER_ROW_H = exports.erRowCenterY = void 0;
+exports.erDiagram = erDiagram;
+/**
+ * ER diagram kit — typed builders for database entity-relationship diagrams.
+ *
+ * The packaged form of what demos/diagrams/table-er.html and er-advanced.html
+ * hand-composed: HTML "table" cards (header, typed columns, PK/FK badges),
+ * crow's-foot cardinality edges, and field-level FK→PK connections via
+ * absolute-layout ports. An embedder writes data:
+ *
+ * ```ts
+ * const spec = erDiagram({
+ *   entities: [
+ *     { id: 'CUSTOMER', columns: [{ name: 'id', type: 'int', pk: true }, …] },
+ *     { id: 'ORDER',    columns: [{ name: 'customer_id', type: 'int', fk: true }, …] },
+ *   ],
+ *   relationships: [
+ *     { from: 'CUSTOMER', to: 'ORDER', label: 'places' },              // table-level
+ *     { from: 'ORDER.customer_id', to: 'CUSTOMER.id' },                // field-level
+ *   ],
+ * });
+ * render(spec, container);
+ * ```
+ */
+const styles_1 = require("./styles");
+const rows_1 = require("./rows");
+const card_1 = require("./card");
+Object.defineProperty(exports, "erRowCenterY", { enumerable: true, get: function () { return card_1.erRowCenterY; } });
+Object.defineProperty(exports, "ER_ROW_H", { enumerable: true, get: function () { return card_1.ER_ROW_H; } });
+Object.defineProperty(exports, "ER_HEAD_H", { enumerable: true, get: function () { return card_1.ER_HEAD_H; } });
+const editing_1 = require("./editing");
+const DEFAULT_WIDTH = 190;
+const CARDINALITY = {
+    'one-to-many': { tail: 'one', head: 'crow-foot' },
+    'one-to-one': { tail: 'one', head: 'one' },
+    'many-to-many': { tail: 'crow-foot', head: 'crow-foot' },
+    'one-to-zero-or-many': { tail: 'one', head: 'zero-or-many' },
+    'one-to-one-or-many': { tail: 'one', head: 'one-or-many' },
+};
+function parseEnd(ref, byId) {
+    const dot = ref.indexOf('.');
+    const entityId = dot === -1 ? ref : ref.slice(0, dot);
+    const entity = byId.get(entityId);
+    if (!entity)
+        throw new Error(`erDiagram: unknown entity "${entityId}" in relationship end "${ref}"`);
+    if (dot === -1)
+        return { entity };
+    const column = ref.slice(dot + 1);
+    const rowIndex = entity.columns.findIndex((c) => c.name === column);
+    if (rowIndex === -1) {
+        throw new Error(`erDiagram: entity "${entityId}" has no column "${column}" (relationship end "${ref}")`);
+    }
+    return { entity, column, rowIndex };
+}
+/**
+ * Build a render() spec for an ER diagram.
+ *
+ * Entities become HTML table cards; relationships become orthogonal edges with
+ * crow's-foot cardinality. A `TABLE.column` end pins the edge to that row via
+ * an absolute-layout port (the FK→PK look). Two edges landing on the same
+ * column are automatically spread apart.
+ */
+function erDiagram(options) {
+    var _a;
+    (0, styles_1.ensureDiagramKitStyles)();
+    const byId = new Map(options.entities.map((e) => [e.id, e]));
+    // Field-level ports are accumulated per entity while walking relationships.
+    const portsByEntity = new Map();
+    // How many edges already landed on a given entity row+side — drives the
+    // spread (dy) so shared columns (a PK referenced twice) don't stack.
+    const rowLandings = new Map();
+    const width = (e) => { var _a; return (_a = e.width) !== null && _a !== void 0 ? _a : DEFAULT_WIDTH; };
+    const fieldPort = (end, side) => {
+        var _a, _b;
+        const entity = end.entity;
+        const key = `${entity.id}#${end.rowIndex}#${side}`;
+        const landing = (_a = rowLandings.get(key)) !== null && _a !== void 0 ? _a : 0;
+        rowLandings.set(key, landing + 1);
+        // Spread repeat landings ±5px around the row centre: 0, -5, +5, -10, …
+        const dy = landing === 0 ? 0 : (landing % 2 === 1 ? -1 : 1) * Math.ceil(landing / 2) * 5;
+        const id = `${entity.id}__${end.column}__${side}__${landing}`;
+        const w = width(entity);
+        const port = {
+            id,
+            side,
+            visible: false,
+            layout: {
+                strategy: 'absolute',
+                args: {
+                    units: 'px',
+                    x: side === 'right' ? w : side === 'left' ? 0 : w / 2,
+                    y: (0, card_1.erRowCenterY)(end.rowIndex),
+                    dy,
+                },
+            },
+        };
+        const bucket = (_b = portsByEntity.get(entity.id)) !== null && _b !== void 0 ? _b : [];
+        bucket.push(port);
+        portsByEntity.set(entity.id, bucket);
+        return id;
+    };
+    const edges = ((_a = options.relationships) !== null && _a !== void 0 ? _a : []).map((rel, i) => {
+        var _a, _b, _c, _d, _e;
+        const from = parseEnd(rel.from, byId);
+        const to = parseEnd(rel.to, byId);
+        const fromSide = (_a = rel.fromSide) !== null && _a !== void 0 ? _a : 'right';
+        const toSide = (_b = rel.toSide) !== null && _b !== void 0 ? _b : 'left';
+        const markers = typeof rel.cardinality === 'object'
+            ? rel.cardinality
+            : CARDINALITY[(_c = rel.cardinality) !== null && _c !== void 0 ? _c : 'one-to-many'];
+        return {
+            id: (_d = rel.id) !== null && _d !== void 0 ? _d : `er-rel-${i + 1}`,
+            source: from.entity.id,
+            target: to.entity.id,
+            label: rel.label,
+            type: 'orthogonal',
+            sourceHandle: from.column !== undefined ? fieldPort(from, fromSide) : fromSide,
+            targetHandle: to.column !== undefined ? fieldPort(to, toSide) : toSide,
+            style: {
+                stroke: (_e = rel.color) !== null && _e !== void 0 ? _e : '#64748b',
+                strokeWidth: 1.5,
+                arrowTail: { type: markers.tail, size: 8, filled: false },
+                arrowHead: { type: markers.head, size: 9, filled: false },
+            },
+        };
+    });
+    const editable = options.editable === true;
+    const nodes = options.entities.map((entity, i) => {
+        var _a;
+        return (Object.assign({ id: entity.id, position: (_a = entity.position) !== null && _a !== void 0 ? _a : { x: 60 + (i % 3) * 340, y: 60 + Math.floor(i / 3) * 280 }, size: { width: width(entity), height: (0, card_1.entityAutoHeight)(entity, editable) }, 
+            // interactive: rows are real DOM targets (hover, row selection, inline
+            // editing) — node drag/select stay geometric in the binder.
+            metadata: Object.assign({ html: { content: (0, card_1.entityCardContent)(entity, editable), interactive: true }, kitEntity: entity, kitEditable: editable }, (options.rowSelection === false ? { kitRowSelection: false } : {})), 
+            // The card draws its own border — the node's default rectangle is hidden
+            // (and re-suppressed on selection by the kit stylesheet).
+            shape: { type: 'rect', fill: 'none', stroke: 'none' }, style: { fill: 'transparent', stroke: 'transparent', strokeWidth: 0 } }, (portsByEntity.has(entity.id) ? { ports: portsByEntity.get(entity.id) } : {})));
+    });
+    return {
+        nodes,
+        edges,
+        finalize: (api) => {
+            var _a, _b, _c, _d;
+            const a = api;
+            // The card draws its OWN selection ring — suppress the node resize handles
+            // on the live model (they'd frame the card in a SECOND rectangle). Set here
+            // because the render-input path does not honour a spec-level `behavior`.
+            const model = (_a = a === null || a === void 0 ? void 0 : a.getModel) === null || _a === void 0 ? void 0 : _a.call(a);
+            if (model)
+                for (const e of options.entities)
+                    (_d = (_c = (_b = model.getNode) === null || _b === void 0 ? void 0 : _b.call(model, e.id)) === null || _c === void 0 ? void 0 : _c.setBehavior) === null || _d === void 0 ? void 0 : _d.call(_c, { resizable: false });
+            if (options.rowSelection !== false && (a === null || a === void 0 ? void 0 : a.container))
+                (0, rows_1.bindRowInteractions)(a);
+            // Editing chrome (dbl-click rename, add/delete column) — opt-in, and safe
+            // to run alongside row selection (it claims control clicks in the capture
+            // phase before the selection handler sees them).
+            if (editable && (a === null || a === void 0 ? void 0 : a.container))
+                (0, editing_1.bindCardEditing)(a);
+        },
+    };
+}
+//# sourceMappingURL=er.js.map

package/src/lib/diagram-kit/er.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"er.js","sourceRoot":"","sources":["../../../../../../libs/element/src/lib/diagram-kit/er.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,181 @@
+/**
+ * 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;
+}
+export declare abstract class CardHandle {
+    protected readonly api: HandleApi;
+    readonly id: string;
+    constructor(api: HandleApi, id: string);
+    /** The live node, or undefined once deleted. Handles never cache it. */
+    protected liveNode(): {
+        getMetadata?(key: string): unknown;
+        size: {
+            width: number;
+            height: number;
+        };
+        state?: {
+            selected?: boolean;
+        };
+    } | undefined;
+    get exists(): boolean;
+    /** Escape hatch to the underlying NodeModel (typed loosely on purpose). */
+    get node(): unknown;
+    get width(): number;
+    get height(): number;
+    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;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    /**
+     * 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;
+}
+/** A column of an {@link ErTable} — itself just (table, name): stateless. */
+export declare class ErField {
+    readonly table: ErTable;
+    private readonly columnName;
+    constructor(table: ErTable, columnName: string);
+    private col;
+    get exists(): boolean;
+    get name(): string;
+    get index(): number;
+    get type(): string | undefined;
+    get pk(): boolean;
+    get fk(): boolean;
+    /** Rename — the field port keeps its id, so attached edges stay glued. */
+    rename(name: string): Promise<boolean>;
+    setType(type: string): Promise<boolean>;
+    setKeys(keys: {
+        pk?: boolean;
+        fk?: boolean;
+    }): Promise<boolean>;
+    /** Remove this column (its ports and attached edges are dropped). */
+    remove(): Promise<boolean>;
+}
+/** The columns collection of an {@link ErTable}. Iterable of {@link ErField}. */
+export declare class ErColumnList implements Iterable<ErField> {
+    private readonly table;
+    constructor(table: ErTable);
+    private cols;
+    get length(): number;
+    names(): string[];
+    at(index: number): ErField | undefined;
+    get(name: string): ErField | undefined;
+    [Symbol.iterator](): Iterator<ErField>;
+    add(column: ErColumn, opts?: {
+        at?: number;
+    }): Promise<boolean>;
+    removeAt(index: number): Promise<boolean>;
+    renameAt(index: number, name: string): Promise<boolean>;
+    patchAt(index: number, patch: Partial<ErColumn>): Promise<boolean>;
+    move(from: number, to: number): Promise<boolean>;
+}
+export declare class ErTable extends CardHandle {
+    readonly columns: ErColumnList;
+    /** A deep COPY of the stored entity spec — never a live reference. */
+    get spec(): ErEntitySpec;
+    get name(): string;
+    rename(name: string): Promise<boolean>;
+    resize(size: {
+        width?: number;
+        height?: number;
+    }): Promise<boolean>;
+    /** The raw delta path — everything above funnels through here. */
+    update(delta: Parameters<typeof updateEntity>[2]): Promise<boolean>;
+}
+/** attributes / methods of a {@link UmlClass} (members are plain strings). */
+export declare class UmlMemberList {
+    private readonly cls;
+    private readonly kind;
+    constructor(cls: UmlClass, kind: 'attributes' | 'methods');
+    list(): string[];
+    get length(): number;
+    at(index: number): string | undefined;
+    add(member: string, opts?: {
+        at?: number;
+    }): Promise<boolean>;
+    removeAt(index: number): Promise<boolean>;
+    renameAt(index: number, member: string): Promise<boolean>;
+}
+export declare class UmlClass extends CardHandle {
+    readonly attributes: UmlMemberList;
+    readonly methods: UmlMemberList;
+    /** A deep COPY of the stored class spec — never a live reference. */
+    get spec(): UmlClassSpec;
+    get name(): string;
+    get abstract(): boolean;
+    get stereotype(): string | undefined;
+    rename(name: string): Promise<boolean>;
+    resize(size: {
+        width?: number;
+        height?: number;
+    }): Promise<boolean>;
+    setAbstract(abstract: boolean): Promise<boolean>;
+    setStereotype(stereotype: string | undefined): Promise<boolean>;
+    update(delta: Parameters<typeof updateClass>[2]): Promise<boolean>;
+}
+/** Typed handle for a kit ER table. Throws for unknown ids / non-kit nodes. */
+export declare function erTable(api: HandleApi, id: string): ErTable;
+/** Typed handle for a kit UML class. Throws for unknown ids / non-kit nodes. */
+export declare function umlClass(api: HandleApi, id: string): UmlClass;
+/** Every kit ER table in the diagram, as handles. */
+export declare function erTables(api: HandleApi): ErTable[];
+/** Every kit UML class in the diagram, as handles. */
+export declare function umlClasses(api: HandleApi): UmlClass[];

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

@@ -0,0 +1,325 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UmlClass = exports.UmlMemberList = exports.ErTable = exports.ErColumnList = exports.ErField = exports.CardHandle = void 0;
+exports.erTable = erTable;
+exports.umlClass = umlClass;
+exports.erTables = erTables;
+exports.umlClasses = umlClasses;
+const tslib_1 = require("tslib");
+const update_1 = require("./update");
+const deep = (v) => JSON.parse(JSON.stringify(v));
+// ---------------------------------------------------------------------------
+// Base
+// ---------------------------------------------------------------------------
+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 tslib_1.__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 tslib_1.__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);
+    }
+}
+exports.CardHandle = CardHandle;
+// ---------------------------------------------------------------------------
+// ER
+// ---------------------------------------------------------------------------
+/** A column of an {@link ErTable} — itself just (table, name): stateless. */
+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);
+    }
+}
+exports.ErField = ErField;
+/** The columns collection of an {@link ErTable}. Iterable of {@link ErField}. */
+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 });
+    }
+}
+exports.ErColumnList = ErColumnList;
+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 (0, update_1.updateEntity)(this.api, this.id, delta);
+    }
+}
+exports.ErTable = ErTable;
+// ---------------------------------------------------------------------------
+// UML
+// ---------------------------------------------------------------------------
+/** attributes / methods of a {@link UmlClass} (members are plain strings). */
+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)) });
+    }
+}
+exports.UmlMemberList = UmlMemberList;
+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 (0, update_1.updateClass)(this.api, this.id, delta);
+    }
+}
+exports.UmlClass = UmlClass;
+// ---------------------------------------------------------------------------
+// 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. */
+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. */
+function umlClass(api, id) {
+    requireKit(api, id, 'kitClass', 'umlClass');
+    return new UmlClass(api, id);
+}
+/** Every kit ER table in the diagram, as handles. */
+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. */
+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