@grafloria/element 0.3.20 → 0.3.21

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

@@ -1,573 +0,0 @@
-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;
-}