@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/models/GroupModel.d.ts

@@ -0,0 +1,573 @@
+import { DiagramEntity } from './DiagramEntity';
+import type { DiagramModel } from './DiagramModel';
+import type { SerializedEntity } from '../types';
+import type { LayoutType, LayoutConfig, FlexboxLayoutConfig, GridLayoutConfig } from '../types/layout.types';
+export interface SerializedGroup extends SerializedEntity {
+    name: string;
+    members: string[];
+    isCollapsed: boolean;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    layoutType?: LayoutType;
+    layoutConfig?: LayoutConfig;
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        width: number;
+        height: number;
+        depth: number;
+    };
+    parentGroupId?: string;
+    padding?: GroupPadding;
+    headerHeight?: number;
+    zIndex?: number;
+    fitMode?: GroupFitMode;
+    constrainChildren?: boolean;
+    collapsedState?: CollapsedState;
+    subgraphLayout?: SubgraphGroupConfig;
+    laneConfig?: LaneConfig;
+    membershipRule?: MembershipRule;
+    capacity?: number;
+}
+/**
+ * Wave-5 Card 7: a SERIALIZABLE declarative membership predicate over a node's
+ * `data` (never eval'd code). Leaves match one field with an operator; branches
+ * compose with all/any/not. Kept intentionally small and closed so it round-
+ * trips and can be reasoned about / edited as data.
+ */
+export type MembershipRule = MembershipLeaf | {
+    all: MembershipRule[];
+} | {
+    any: MembershipRule[];
+} | {
+    not: MembershipRule;
+};
+export interface MembershipLeaf {
+    /** Dot-free key looked up on the node's `data` map. */
+    field: string;
+    op: 'eq' | 'ne' | 'in' | 'nin' | 'gt' | 'gte' | 'lt' | 'lte' | 'exists' | 'matches';
+    /** Comparison operand (array for in/nin; regex source string for matches). */
+    value?: unknown;
+}
+/**
+ * Wave-5 Card 5: a group's own compound-layout configuration — the subset of
+ * the GroupInfo layout contract that is intrinsic to the group and round-trips.
+ * Padding/header come from Card 3 (padding/headerHeight); size clamps come from
+ * fitToContents.
+ */
+export interface SubgraphGroupConfig {
+    /**
+     * Algorithm for THIS group's contents. 'inherit' uses the parent/default.
+     *
+     * Wave 7 Card 4: any name in the layout registry works here (force, spectral,
+     * community, or an extension-registered engine), not just the dagre|elk pair
+     * wave 5 hard-coded — nested layout resolves the name against the registry.
+     * An unknown name falls back to the built-in grid rather than throwing.
+     */
+    algorithm?: 'dagre' | 'elk' | 'grid' | 'inherit' | (string & {});
+    /** Pinned: neither laid out internally nor moved by the parent layout. */
+    fixed?: boolean;
+    /** Opaque options forwarded to the chosen layout adapter. */
+    layoutOptions?: Record<string, unknown>;
+}
+/**
+ * Wave-5 Card 6: swimlanes & pools as a GENERIC banded group (not BPMN-named).
+ * A `pool` group tiles its child `lane` groups into bands along one axis; each
+ * `lane` is an ordinary group (so drop-to-assign, membership, constraints all
+ * reuse the existing machinery). This is intrinsic band config that round-trips.
+ */
+export interface LaneConfig {
+    /** 'pool' owns the band grid; 'lane' is one band inside a pool. */
+    role: 'pool' | 'lane';
+    /**
+     * Band axis. 'horizontal' → lanes are rows stacked along Y (each spans the
+     * pool width). 'vertical' → lanes are columns along X (each spans the height).
+     * Set on the pool; lanes carry a copy for convenience.
+     */
+    orientation: 'horizontal' | 'vertical';
+    /** Pool only: ordered child lane group ids (band order). */
+    laneOrder?: string[];
+    /**
+     * Pool only: title-band thickness reserved along the main axis start (left for
+     * horizontal pools, top for vertical pools).
+     */
+    headerSize?: number;
+    /** Lane only: relative cross-axis size when not fixed (default 1). */
+    weight?: number;
+    /** Lane only: absolute cross-axis size (pins the band, overrides weight). */
+    fixedSize?: number;
+}
+/**
+ * Wave-5 Card 4: the reversible snapshot captured when a group collapses.
+ * Stored (serialized) on the group so a collapsed diagram round-trips and can
+ * be expanded losslessly after a save/load — not just within one session.
+ */
+export interface CollapsedState {
+    /** The hidden placeholder node that presents the group as a node endpoint. */
+    proxyNodeId: string;
+    /** The group's exact geometry before it shrank (restored verbatim on expand). */
+    savedGeometry?: {
+        position: {
+            x: number;
+            y: number;
+        };
+        size?: {
+            width: number;
+            height: number;
+            depth: number;
+        };
+        bounds?: GroupRect;
+    };
+    /** Member (node) world positions at collapse time (restored on expand). */
+    savedPositions: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Members whose visibility we toggled, with their prior `visible` value. */
+    hiddenNodes: Array<{
+        nodeId: string;
+        prevVisible: boolean;
+    }>;
+    /**
+     * Serialized links removed at collapse time (internal links + the parallel
+     * boundary links that were aggregated away). Re-created verbatim on expand.
+     */
+    removedLinks: any[];
+    /**
+     * Boundary links that SURVIVED as proxy links: one per (external endpoint)
+     * bundle, re-pointed to the placeholder node. Records the original endpoint
+     * so expand can restore it, plus how many raw edges it now represents.
+     */
+    proxyLinks: Array<{
+        linkId: string;
+        end: 'source' | 'target';
+        originalPortId: string;
+        originalNodeId?: string;
+        aggregatedCount: number;
+    }>;
+}
+/** Wave-5 Card 3: per-side padding (a scalar expands to all four sides). */
+export type GroupPadding = number | {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+};
+/**
+ * Defaults for groups AUTHORED in code (constructor path). A fitted frame needs
+ * breathing room and a title band or its label lands under the first member.
+ * Loaded documents are exempt: restore assigns the stored values (padding
+ * verbatim — possibly undefined, which getPadding() resolves to 0 — and
+ * headerHeight number-or-0), so legacy geometry is byte-stable.
+ */
+export declare const DEFAULT_GROUP_PADDING = 16;
+export declare const DEFAULT_GROUP_HEADER_HEIGHT = 24;
+/**
+ * Wave-5 Card 3: how {@link GroupModel.fitToContents} reconciles the freshly
+ * computed content rectangle with the group's current rectangle.
+ * - `exact`      — snap to the content rectangle (default).
+ * - `grow-only`  — never shrink below the current rectangle (union).
+ * - `shrink-only`— never grow beyond the current rectangle (intersection-ish).
+ */
+export type GroupFitMode = 'exact' | 'grow-only' | 'shrink-only';
+/** A resolved rectangle (all four sides present). */
+export interface GroupRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Options for {@link GroupModel.fitToContents}. */
+export interface FitToContentsOptions {
+    /** Override the group's stored {@link GroupModel.fitMode} for this call. */
+    mode?: GroupFitMode;
+    /**
+     * Deep-recursive fit: fit every descendant group first (deepest first) so a
+     * parent fits around already-fitted children. Requires a diagram.
+     */
+    deepRecursive?: boolean;
+}
+/**
+ * Predicate used to gate group membership (Wave-2).
+ * Return false to reject a candidate entity from joining the group.
+ * @param candidateId - id of the node/group being added
+ * @param group - the group the candidate would join
+ */
+export type MemberValidation = (candidateId: string, group: GroupModel) => boolean;
+export declare class GroupModel extends DiagramEntity {
+    name: string;
+    members: Set<string>;
+    isCollapsed: boolean;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    layoutType: LayoutType;
+    layoutConfig?: LayoutConfig;
+    position: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        width: number;
+        height: number;
+        depth: number;
+    };
+    parentGroupId?: string;
+    memberValidation?: MemberValidation;
+    isHovered: boolean;
+    padding?: GroupPadding;
+    headerHeight: number;
+    zIndex: number;
+    fitMode: GroupFitMode;
+    constrainChildren: boolean;
+    collapsedState?: CollapsedState;
+    subgraphLayout?: SubgraphGroupConfig;
+    laneConfig?: LaneConfig;
+    membershipRule?: MembershipRule;
+    capacity?: number;
+    constructor(config: {
+        id?: string;
+        name: string;
+    });
+    /**
+     * Resolve the owning diagram, preferring an explicit argument and falling
+     * back to the reference stashed in metadata by DiagramModel.addGroup.
+     */
+    private resolveDiagram;
+    /**
+     * Whether `candidateId` may legally join this group (Wave-2).
+     * Rejects self-membership, ancestor cycles (adding an ancestor group as a
+     * member would create a containment loop), and candidates failing the
+     * per-group `memberValidation` predicate. Node candidates only run the
+     * predicate check (nodes can't form group cycles).
+     */
+    canAddMember(candidateId: string, diagram?: DiagramModel): boolean;
+    /**
+     * Wave-5 Card 7: WIP state for the capacity limit. 'under' = room to spare,
+     * 'full' = exactly at the limit (the visual warning threshold), 'over' = past
+     * it (only reachable by lowering capacity below the current count). Returns
+     * 'unlimited' when no capacity is set.
+     */
+    getWipState(): {
+        count: number;
+        capacity?: number;
+        state: 'unlimited' | 'under' | 'full' | 'over';
+    };
+    /** Wave-5 Card 7: true when at or beyond the capacity limit (warning state). */
+    isOverCapacity(): boolean;
+    /** Set (or clear) the capacity / WIP limit, tracked for undo/diff. */
+    setCapacity(capacity: number | undefined): void;
+    /**
+     * Add member to group.
+     *
+     * When the member is itself a group, this establishes containment by setting
+     * the child's `parentGroupId` (detaching it from any previous parent), which
+     * keeps the nesting tree consistent for getAncestors/getDescendants. Members
+     * that would create a cycle or fail `memberValidation` are rejected (no-op).
+     */
+    addMember(entityId: string, diagram?: DiagramModel): void;
+    /**
+     * Remove member from group. When the member is a group whose parent is this
+     * group, its `parentGroupId` back-pointer is cleared so the nesting tree
+     * stays consistent.
+     */
+    removeMember(entityId: string, diagram?: DiagramModel): boolean;
+    /**
+     * Make `child` a nested group of this group: detach from previous parent's
+     * members and point `parentGroupId` here. Uses protected access allowed
+     * between GroupModel instances.
+     */
+    private linkChildGroup;
+    /**
+     * Clear this group's parent back-pointer (used when detached from a parent).
+     */
+    private clearParentGroupId;
+    /**
+     * Reparent this group under `newParentId` (or detach when undefined),
+     * keeping both the `parentGroupId` pointer and the parents' `members` sets
+     * consistent. Rejects cycles (a group cannot be nested under one of its own
+     * descendants) and returns false without mutating anything.
+     */
+    setParent(newParentId: string | undefined, diagram?: DiagramModel): boolean;
+    /**
+     * Set transient drag-hover highlight state and notify listeners (Wave-2).
+     * Renderers/canvas can subscribe to 'hover:changed' to outline a drop target.
+     */
+    setHovered(hovered: boolean): void;
+    /**
+     * Expand the group
+     */
+    expand(): void;
+    /**
+     * Collapse the group
+     */
+    collapse(): void;
+    /**
+     * Wave-5 Card 4: set (or clear) the reversible collapse snapshot. Tracked as a
+     * change so the incremental diff-capture serializes it and undo/redo see it.
+     */
+    setCollapsedState(state: CollapsedState | undefined): void;
+    /**
+     * Set layout configuration (Phase 1.7)
+     * @param type - Layout type ('flexbox' or 'grid')
+     * @param config - Layout configuration object
+     */
+    setLayout(type: 'flexbox', config: FlexboxLayoutConfig): void;
+    setLayout(type: 'grid', config: GridLayoutConfig): void;
+    /**
+     * Clear layout configuration (Phase 1.7)
+     */
+    clearLayout(): void;
+    /**
+     * Get layout configuration (Phase 1.7)
+     */
+    getLayout(): {
+        type: LayoutType;
+        config?: LayoutConfig;
+    };
+    /**
+     * Check if group has layout configured (Phase 1.7)
+     */
+    hasLayout(): boolean;
+    /**
+     * Get layout as flexbox config (Phase 1.7)
+     * @throws Error if layout is not flexbox
+     */
+    getFlexboxLayout(): FlexboxLayoutConfig;
+    /**
+     * Get layout as grid config (Phase 1.7)
+     * @throws Error if layout is not grid
+     */
+    getGridLayout(): GridLayoutConfig;
+    /**
+     * Calculate bounds from member nodes using global bounds
+     */
+    calculateBounds(diagram: DiagramModel): void;
+    /**
+     * Resolve {@link padding} to a full four-sided rectangle. `undefined` (the
+     * author never said) resolves to {@link DEFAULT_GROUP_PADDING}; an explicit
+     * value — including the 0 that loaders pin for legacy documents — is taken
+     * as written.
+     */
+    getPadding(): {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /**
+     * The group's outer frame rectangle in world coordinates. Prefers explicit
+     * geometry (position + size) and falls back to the derived member `bounds`,
+     * matching how GroupMembershipService hit-tests a group.
+     */
+    getOuterBounds(): GroupRect;
+    /**
+     * The rectangle members must stay inside: the outer frame minus padding and
+     * minus the header band (which is reserved at the top). Never returns a
+     * negative width/height.
+     */
+    getInnerBounds(): GroupRect;
+    /**
+     * Auto-fit the group frame to its members' bounding box plus padding and the
+     * header band. This is the real consumer of `padding`/`headerHeight` that
+     * `calculateBounds` (a tight, padding-free box) never was.
+     *
+     * Member groups contribute their own OUTER frame (so a parent fits around a
+     * nested group's full extent, not just its raw member points). With
+     * `deepRecursive`, descendant groups are fitted first (deepest first) so the
+     * parent fits around already-fitted children.
+     *
+     * The computed content rectangle is reconciled with the current frame per the
+     * effective fit mode (grow-only / shrink-only / exact) and written to both
+     * `position`/`size` (authoritative geometry) and `bounds` (hit-test rect).
+     * No-op with no positioned members (nothing to fit around).
+     */
+    fitToContents(diagram?: DiagramModel, options?: FitToContentsOptions): void;
+    /**
+     * Bounding box (world coords) of this group's members. Nodes contribute their
+     * global bounds; member groups contribute their outer frame. Returns
+     * undefined when nothing is positioned.
+     */
+    private computeMemberExtent;
+    /** Apply a fit mode to reconcile a freshly computed rect with the current frame. */
+    private reconcileFit;
+    /**
+     * Write a world rectangle into the group's authoritative geometry
+     * (position + size) and the derived hit-test `bounds`, keeping the existing
+     * `depth` when present. Tracks a single 'bounds' change for undo/diff.
+     */
+    setFrame(rect: GroupRect): void;
+    /**
+     * Clamp a member node so it stays fully inside the group's inner extent.
+     * No-op unless `constrainChildren` is set and the node is a direct member.
+     * Returns true when the node was actually moved. Absolute-coordinate model:
+     * this adjusts the node's world position directly.
+     */
+    clampChildToExtent(nodeId: string, diagram?: DiagramModel): boolean;
+    /**
+     * Wave-5 Card 4: restore raw geometry (position + optional size + bounds)
+     * captured before a collapse. Unlike setFrame this permits size === undefined
+     * so a group that had no explicit frame is restored to exactly that.
+     */
+    restoreGeometry(geo: {
+        position: {
+            x: number;
+            y: number;
+        };
+        size?: {
+            width: number;
+            height: number;
+            depth: number;
+        };
+        bounds?: GroupRect;
+    }): void;
+    /** Set the group's stacking index (lower renders further back). */
+    setZIndex(z: number): void;
+    /**
+     * Bring this group in front of every other group (highest zIndex + 1).
+     * Minimal z-order API — the renderer honors zIndex ordering.
+     */
+    bringToFront(diagram?: DiagramModel): void;
+    /** Send this group behind every other group (lowest zIndex - 1). */
+    sendToBack(diagram?: DiagramModel): void;
+    /**
+     * Re-entrancy guard. The cycle this closes is real and one hop long: layout
+     * writes a child's size → the child notifies its containers → the container lays
+     * out again → it writes the child's size… Held for the duration of one pass;
+     * every push that arrives DURING a pass is dropped, because that pass is already
+     * producing the answer the push would ask for.
+     */
+    private layoutInFlight;
+    /**
+     * Is push-driven reflow active for this container?
+     *
+     * DEFAULT ON for any group that declares a layout — a container that says
+     * "I am a 12-column grid" and then lets its children drift is not a layout
+     * container. `metadata('autoLayout')` survives as the explicit override:
+     * set it to `false` to freeze the children (useful while dragging, or for a
+     * container whose positions are authored by hand). Setting it to `true`
+     * remains valid and is now simply the default.
+     */
+    isAutoLayoutEnabled(): boolean;
+    /**
+     * THE push entry point: "something changed, reflow if you are supposed to."
+     * Distinct from {@link applyLayout}, which is the unconditional PULL — an
+     * explicit `applyLayout()` still works on an opted-out container.
+     */
+    requestLayout(diagram?: DiagramModel): void;
+    /**
+     * Apply layout to member nodes (Phase 1.7+)
+     * Positions child nodes based on flex or grid layout configuration
+     */
+    applyLayout(diagram?: DiagramModel): void;
+    /**
+     * D — auto-layout SKIPS LOCKED MEMBERS.
+     *
+     * A locked member keeps both its position and its size, but still consumes its
+     * slot in the flow (callers advance the cursor by the child's CURRENT size), so
+     * the container never stacks another widget on top of a pinned one. This is the
+     * precedent `LayoutManager` already set for graph layouts — it restores locked
+     * node positions after every run — and it is what "pin this tile" means to
+     * someone building a dashboard.
+     */
+    private isPinned;
+    /**
+     * Move a member. Nodes go through `setPosition` (tracked + propagating);
+     * member GROUPS go through `setFrame` when they have a frame, which is what
+     * cascades the reflow down into a nested container's own children.
+     */
+    private placeEntity;
+    /**
+     * Resize a member along one or both axes. `undefined` leaves that axis alone.
+     * Nodes go through `setSize` so the write is tracked and honours the per-node
+     * lock; member groups go through `setFrame` so their own children follow.
+     */
+    private resizeEntity;
+    /**
+     * B — the per-item flex config, finally read. `order` is a stable sort key
+     * (equal orders keep membership order), exactly like CSS.
+     */
+    private orderFlexEntities;
+    /** FlexItemConfig of a member, if it is a node that carries one. */
+    private flexItemOf;
+    /** GridItemConfig of a member, if it is a node that carries one. */
+    private gridItemOf;
+    /**
+     * Apply flexbox layout to entities (nodes or groups).
+     *
+     * B — a real single-pass flex algorithm, written axis-agnostically so `row` and
+     * `column` share one code path: line breaking (`wrap`), `flexGrow` distribution,
+     * `justifyContent` on the main axis, and `alignItems`/`alignSelf` (including
+     * `stretch`) on the cross axis. Previously only `justifyContent: 'center'` and
+     * `alignItems: 'center'` existed and `wrap` was unread.
+     *
+     * The Bootstrap-style `columns` path is untouched and still takes priority for
+     * row containers — see {@link applyColumnBasedLayout}.
+     */
+    private applyFlexboxLayout;
+    /**
+     * Main-axis distribution for one flex line: how far the first item is pushed in,
+     * and how much EXTRA space goes between consecutive items (on top of `gap`).
+     * `start` (and anything unrecognised) is the identity, so a container with no
+     * size — where `free` is passed as 0 — always lays out from the content origin.
+     */
+    private resolveJustify;
+    /**
+     * Cross-axis offset of one item inside its line. `stretch` has already resized
+     * the item by the time this runs, so it lands at the line start like `start`.
+     * `baseline` degrades to `start`: this model has no text baselines to align to,
+     * and quietly inventing one would be worse than saying so.
+     */
+    private resolveAlign;
+    /**
+     * Apply column-based layout (like Bootstrap 12-column grid)
+     */
+    private applyColumnBasedLayout;
+    /**
+     * Apply grid layout to entities (nodes or groups).
+     *
+     * B — placement now comes from each item's {@link GridItemConfig} (explicit
+     * `columnStart`/`rowStart` lines and `columnEnd`/`rowEnd` spans), not from the
+     * member's ARRAY INDEX. Items with no explicit placement auto-flow into the
+     * first cell no explicit item has claimed, in `autoFlow` order. Tracks are
+     * uniform: derived from the container's content box when it has one, and from
+     * the widest/tallest member otherwise (which is what the old per-entity
+     * arithmetic already produced for the equal-sized children it was written for).
+     */
+    private applyGridLayout;
+    /**
+     * Resolve every member to a 0-based grid cell + span.
+     *
+     * Two passes, because explicit placement must WIN: pass 1 reserves the cells
+     * claimed by items with a `GridItemConfig` line (or a `gridColumn`/`gridRow`
+     * metadata fallback); pass 2 flows the rest into the first cell still free.
+     * Without the reservation an auto item would happily land under a pinned one —
+     * which is precisely the bug "placement by array index" always had.
+     */
+    private resolveGridPlacements;
+    /**
+     * Normalize padding to all four sides
+     */
+    private normalizePadding;
+    /**
+     * Parse grid template columns to get column count
+     */
+    private parseGridColumns;
+    /**
+     * Serialize to JSON
+     */
+    serialize(): SerializedGroup;
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(data: SerializedGroup): GroupModel;
+}