@lifecorner/angular-ui-kit 3.4.0 → 3.5.0

package/types/lifecorner-angular-ui-kit-dependency-viewer.d.ts

@@ -0,0 +1,568 @@
+import * as i0 from "@angular/core";
+export type DependencyNodeStatus = 'default' | 'active' | 'success' | 'warning' | 'error' | 'muted';
+export type DependencyDirection = 'horizontal' | 'vertical';
+export type DependencyRelation = 'depends' | 'blocks' | 'references' | 'requires' | 'extends' | 'implements' | 'uses';
+/**
+ * How nodes are placed.
+ *
+ * - `tree` — column = depth in the `children` tree; `dependsOn` links are drawn
+ *   over the top as cross-references and don't move anything.
+ * - `layered` — column = depth in the *dependency* graph (Sugiyama). Every link is
+ *   a precedence constraint, so a node always sits past everything it depends on.
+ */
+export type DependencyLayout = 'tree' | 'layered';
+/**
+ * How the graph is scaled into the frame.
+ *
+ * - `none` — no fitting; the viewport is whatever the user panned/zoomed to.
+ * - `contain` — shrink until all of it fits, both axes.
+ * - `fit-width` — shrink to the frame's *width* only and let the viewer grow
+ *   taller, so the page scrolls instead of the nodes shrinking out of legibility.
+ */
+export type DependencyFitMode = 'none' | 'contain' | 'fit-width';
+export interface DependencyEdgeDef {
+  /** Target node id */
+  id: string;
+  /** Relationship type — drives edge colour and dash style */
+  relation?: DependencyRelation;
+  /**
+   * Free-form edge label, for graphs whose relationship vocabulary is wider than
+   * `DependencyRelation` (e.g. `CALLS`, `HAS_COLUMN`, `AUTHORED_BY`). Shown
+   * verbatim instead of the `relation` label; colouring still follows `relation`,
+   * which may be omitted for a generic look.
+   */
+  relationLabel?: string;
+}
+export interface DependencyNode {
+  /** Unique identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Optional description */
+  description?: string;
+  /** Optional icon name */
+  icon?: string;
+  /** Visual status / color */
+  status?: DependencyNodeStatus;
+  /**
+   * Category of the node (e.g. `Class`, `Table`, `Feature`). Colours the node via
+   * the `typeColors` input and drives the type legend. Takes precedence over
+   * `status` for the fill; `status` still applies when no type colour resolves.
+   */
+  type?: string;
+  /**
+   * Number of neighbours that exist but aren't part of `children` — rendered as a
+   * "+N" marker. Use when a node's neighbourhood is capped (god nodes) so the
+   * truncation is visible instead of silent.
+   */
+  moreCount?: number;
+  /** Child nodes: items this node is required for (right / bottom side) */
+  children?: DependencyNode[];
+  /** Dependencies: items this node depends on (shown as cross-reference edges) */
+  dependsOn?: DependencyEdgeDef[];
+  /**
+   * Opaque payload. Never read or interpreted by the component; handed back
+   * unchanged on `nodeSelect` / `nodeExpand` so callers can carry their own
+   * metadata (keys, labels, file paths, …) through the viewer.
+   */
+  data?: Record<string, unknown>;
+}
+interface LayoutNode {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: string;
+  status: DependencyNodeStatus;
+  type?: string;
+  moreCount?: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** The label as drawn: wrapped to the box, last line ellipsised if it had to be. */
+  lines: string[];
+  /** `lines` don't carry the whole label — the template offers it as a tooltip. */
+  truncated: boolean;
+  depth: number;
+  parentId: string | null;
+  incomingCount: number;
+  outgoingCount: number;
+}
+interface LayoutEdge {
+  id: string;
+  path: string;
+  sourceId: string;
+  targetId: string;
+  relation?: DependencyRelation;
+  /** Resolved display label (free-form `relationLabel` wins over the relation's) */
+  label?: string;
+  labelX: number;
+  labelY: number;
+  /** How the label hangs off (labelX, labelY): centred on it, or starting/ending there. */
+  labelAnchor?: LabelAnchor;
+  color: string;
+  dashed: boolean;
+  /** Draws it as a secondary link: dimmed, and out of the layout's main flow. */
+  isCrossRef: boolean;
+  /** Whether to cap the edge with an arrowhead. */
+  arrow: boolean;
+  /** Arrow marker id suffix — always a known relation, so the marker resolves */
+  marker: DependencyRelation;
+  /** Set on bowed routes, so overlapping bows can be spread into lanes afterwards. */
+  bow?: BowInfo;
+}
+type LabelAnchor = 'start' | 'middle' | 'end';
+type BowSide = 'below' | 'above' | 'right' | 'left';
+/**
+ * A bowed route, described well enough to draw it again further out. `column` is
+ * the outermost box edge on the bow's side — the line that identifies which bows
+ * share a gutter — and `base` the line the bow actually clears (the boxes, or
+ * their toggle discs); `lo`/`hi` is the span it covers along that line. Together
+ * that is what lane assignment needs to know which bows collide.
+ */
+interface BowInfo {
+  side: BowSide;
+  column: number;
+  base: number;
+  /** Where the bow peaks, on the axis it bows along. */
+  apex: number;
+  lo: number;
+  hi: number;
+  source: LayoutNode;
+  target: LayoutNode;
+  obstacles: LayoutNode[];
+  dir: DependencyDirection;
+}
+/**
+ * Dependency viewer component for visualizing hierarchical and cross-cutting relationships.
+ *
+ * Features:
+ * - Tree layout (depth in the `children` nesting) and layered/DAG layout (depth in
+ *   the dependency graph), via `layout`
+ * - Horizontal (left-to-right) and vertical (top-to-bottom) layout directions
+ * - Boxes sized to their labels: one width per graph (160–240px), labels wrapping
+ *   onto a second line past the cap and ellipsised (with a tooltip) past that
+ * - Bidirectional dependencies: children (right/down) and dependsOn (cross-references)
+ * - Cross-references routed clear of the boxes: down the gutter to a later level,
+ *   beside the level for siblings, in nested lanes where several overlap
+ * - Relationship types: depends, blocks, references, requires, extends, implements, uses
+ * - Edge labels showing relationship type
+ * - Dashed vs solid edges per relationship category
+ * - Color-coded edges per relationship type
+ * - Node status colors (default, active, success, warning, error, muted)
+ * - Pan and zoom controls with mouse wheel support
+ * - Fitting (`fitMode` / `autoFit`, `minNodeSize`) and a static, non-navigable
+ *   mode (`interactive: false`)
+ * - Collapsible sub-trees
+ * - Interactive node selection with detail panel
+ * - Legend showing active relationship types
+ * - SVG arrowhead markers on cross-reference edges
+ * - Dark/light theme support
+ *
+ * ## Feeding it a graph
+ *
+ * `root` takes a single node (a tree) or an array (a forest — the shape to use for
+ * a flat set of items related only by `dependsOn`). Either way the input is treated
+ * as a graph: a link back to a node that already has a place in the layout — a
+ * cycle, or a node reached from a second parent — is drawn as a cross-reference
+ * arrow instead of being followed. Every node is laid out exactly once, and no
+ * input can make the layout recurse forever.
+ *
+ * ## Picking a layout
+ *
+ * `tree` (default) answers "what contains what": the column is the depth in the
+ * `children` nesting, and `dependsOn` links are drawn over the top without moving
+ * anything.
+ *
+ * `layered` answers "what has to happen first": the column is the depth in the
+ * dependency graph, so a node always sits past everything it depends on. Reach for
+ * it whenever the question is about order or impact rather than containment —
+ * a tree layout can only approximate that by first reducing the graph to a
+ * spanning tree, which throws away every link that doesn't fit one parent per node.
+ *
+ * For incremental exploration, hand in a wider `root` per step and let
+ * `nodeExpand` drive the loading. Pan, zoom, collapse state and selection all
+ * survive a `root` swap, and `anchorNodeId` (defaulting to the selected node)
+ * keeps the viewport pinned while the graph grows around it.
+ *
+ * @example
+ * ```html
+ * <lc-dependency-viewer [root]="specTree" direction="horizontal" />
+ * ```
+ *
+ * @example Order of work — a flat set of items, laid out by their dependencies
+ * ```html
+ * <lc-dependency-viewer
+ *   [root]="items()"
+ *   layout="layered"
+ *   direction="horizontal"
+ *   fitMode="fit-width"
+ *   (nodeSelect)="openItem($event)"
+ * />
+ * ```
+ *
+ * @example Static overview — the whole graph at a glance, click-through only
+ * ```html
+ * <lc-dependency-viewer
+ *   [root]="graph()"
+ *   [autoFit]="true"
+ *   [interactive]="false"
+ *   height="360px"
+ *   (nodeSelect)="openDetail($event)"
+ * />
+ * ```
+ *
+ * @example Incremental graph exploration
+ * ```html
+ * <lc-dependency-viewer
+ *   [root]="graph()"
+ *   [anchorNodeId]="anchor()"
+ *   [typeColors]="{ Alpha: '#c1e3e9' }"
+ *   (nodeSelect)="showDetails($event)"
+ *   (nodeExpand)="loadNeighbours($event)"
+ * />
+ * ```
+ */
+export declare class DependencyViewerComponent {
+  /**
+   * The graph to draw. A single node is the root of a tree; an array is a forest,
+   * which is how you feed a flat set of items that has no natural root — e.g. the
+   * specs of a plan, related only by `dependsOn`.
+   */
+  readonly root: import("@angular/core").InputSignal<DependencyNode | DependencyNode[]>;
+  readonly direction: import("@angular/core").InputSignal<DependencyDirection>;
+  readonly height: import("@angular/core").InputSignal<string>;
+  /**
+   * `tree` (default) places nodes by their depth in the `children` nesting, and
+   * draws `dependsOn` links over the top as cross-references.
+   *
+   * `layered` places them by their depth in the *dependency* graph: a node always
+   * sits past everything it depends on, transitively, and nodes that depend on
+   * nothing start the first layer. That makes `direction="horizontal"` read as an
+   * order of work — left to right — which a tree layout can only approximate by
+   * first throwing away every link that doesn't fit a single-parent hierarchy.
+   *
+   * Use `layered` for process, sequencing and impact views; `tree` for containment
+   * hierarchies, where the nesting *is* the structure.
+   */
+  readonly layout: import("@angular/core").InputSignal<DependencyLayout>;
+  readonly showToolbar: import("@angular/core").InputSignal<boolean>;
+  readonly showEdgeLabels: import("@angular/core").InputSignal<boolean>;
+  readonly edgeWidth: import("@angular/core").InputSignal<number>;
+  /**
+   * Scales and centres the graph so that all of it fits the canvas, and re-fits
+   * whenever the container or the graph changes size. Turns the viewer into an
+   * overview: nothing to pan or zoom to, everything visible at once.
+   *
+   * Shrinks only — the fit never enlarges past 100%, so a two-node graph keeps its
+   * natural size instead of ballooning to fill the frame.
+   *
+   * Pair with `interactive: false` for a purely static display.
+   *
+   * Shorthand for `fitMode="contain"`, which supersedes it.
+   */
+  readonly autoFit: import("@angular/core").InputSignal<boolean>;
+  /**
+   * How the graph is scaled into the frame. Defaults to `autoFit`'s setting —
+   * `contain` when it is on, `none` when it isn't — and overrides it when set.
+   *
+   * `contain` fits both axes, so everything is visible at once but a big graph
+   * shrinks to get there. `fit-width` fits the width only and lets the viewer grow
+   * as tall as the graph needs, so the nodes keep a readable size and the *page*
+   * scrolls; the graph itself never scrolls internally. Past roughly 20 nodes a
+   * process view generally wants `fit-width`.
+   */
+  readonly fitMode: import("@angular/core").InputSignal<DependencyFitMode | null>;
+  /**
+   * Smallest node width, in px, that fitting may shrink to. Below it the fit stops
+   * scaling down and lets the graph overflow instead — which `fit-width` turns into
+   * page scroll, and `contain` into clipping. Pair it with `fit-width`.
+   *
+   * Nodes are 160px wide unscaled (wider — up to 240px — when the graph's labels
+   * need it), so e.g. `80` allows shrinking to half size.
+   */
+  readonly minNodeSize: import("@angular/core").InputSignal<number | null>;
+  /**
+   * Viewport navigation: drag-to-pan, wheel-zoom and the toolbar's zoom buttons.
+   * `false` freezes the viewport — node selection, expansion and collapse keep
+   * working, so `nodeSelect` still fires in a static viewer.
+   */
+  readonly interactive: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Node the viewport holds still across `root` updates. Defaults to the node the
+   * user last selected, which keeps click-to-expand steady without any wiring.
+   * Set it explicitly to anchor somewhere else (e.g. a deep-linked node).
+   */
+  readonly anchorNodeId: import("@angular/core").InputSignal<string | null>;
+  /** Fill colour per `DependencyNode.type`, e.g. `{ Class: '#8ea475' }`. */
+  readonly typeColors: import("@angular/core").InputSignal<Record<string, string>>;
+  /** Relations to hide. Cross-reference edges of these types aren't rendered. */
+  readonly hiddenRelations: import("@angular/core").InputSignal<readonly DependencyRelation[]>;
+  /** Node types to hide, matched against `DependencyNode.type`. */
+  readonly hiddenTypes: import("@angular/core").InputSignal<readonly string[]>;
+  /** Tooltip and accessible name of the zoom-in button. */
+  readonly zoomInLabel: import("@angular/core").InputSignal<string>;
+  /** Tooltip and accessible name of the zoom-out button. */
+  readonly zoomOutLabel: import("@angular/core").InputSignal<string>;
+  /** Tooltip and accessible name of the reset-zoom button. */
+  readonly resetZoomLabel: import("@angular/core").InputSignal<string>;
+  /** Prefix of the depth in the detail panel. */
+  readonly depthLabel: import("@angular/core").InputSignal<string>;
+  /** Prefix of the child count in the detail panel. */
+  readonly childrenLabel: import("@angular/core").InputSignal<string>;
+  /** Prefix of the dependency count in the detail panel. */
+  readonly dependsOnLabel: import("@angular/core").InputSignal<string>;
+  /** Heading of the dependency list in the detail panel. */
+  readonly dependenciesLabel: import("@angular/core").InputSignal<string>;
+  /** Fires when a node is selected (not on deselect), with the original node incl. `data`. */
+  readonly nodeSelect: import("@angular/core").OutputEmitterRef<DependencyNode>;
+  /** Fires on double-click — the hook for "expand this node's neighbourhood". */
+  readonly nodeExpand: import("@angular/core").OutputEmitterRef<DependencyNode>;
+  protected zoom: import("@angular/core").WritableSignal<number>;
+  protected panX: import("@angular/core").WritableSignal<number>;
+  protected panY: import("@angular/core").WritableSignal<number>;
+  protected selectedNodeId: import("@angular/core").WritableSignal<string | null>;
+  protected collapsedIds: import("@angular/core").WritableSignal<Set<string>>;
+  private isPanning;
+  private lastMouseX;
+  private lastMouseY;
+  private readonly hostEl;
+  private readonly canvasRef;
+  /** Last known layout position of the anchor, to compensate pan after a relayout. */
+  private anchorPos;
+  /** Template constants for laying out the label lines. */
+  protected readonly lineHeight = 15;
+  protected readonly baselineShift = 4;
+  /**
+   * Measures label text in the font the labels are drawn in. Built once, on first
+   * use — the host's font is what the SVG text inherits, and it isn't known until
+   * the component is in the document.
+   */
+  private textMeasure;
+  private measureText;
+  private roots;
+  protected effectiveRoots: import("@angular/core").Signal<DependencyNode[]>;
+  private allOriginalNodes;
+  /** Box size and label lines, sized over the whole input — see `measureNodes`. */
+  private nodeMetrics;
+  /**
+   * The laid-out graph. Named `graph` rather than `layout` because `layout` is the
+   * input that picks *how* it gets laid out.
+   */
+  protected graph: import("@angular/core").Signal<{
+    nodes: LayoutNode[];
+    edges: LayoutEdge[];
+    nodeMap: Map<string, LayoutNode>;
+    width: number;
+    height: number;
+  }>;
+  /**
+   * Tree layout over the forest: each root gets its own band along the secondary
+   * axis. A `visited` set shared by all of them keeps a node that hangs off two
+   * roots from being laid out twice — the second link becomes a cross-reference,
+   * exactly as a second parent within one tree does.
+   */
+  private layoutTree;
+  /**
+   * Height `fit-width` derived from the graph, or `null` under any other mode.
+   *
+   * `fit-width` scales to the frame's width and lets the height follow the graph,
+   * so a tall graph runs past the frame and the *page* scrolls instead of the nodes
+   * shrinking out of legibility. The height is therefore always the graph's, never
+   * the frame's — including when the graph is the shorter of the two. Deriving it
+   * unconditionally is also what keeps the fit stable: this height becomes the
+   * canvas's, so a fit that consulted the canvas height would be reading back its
+   * own last output and could flip between two answers forever.
+   */
+  protected contentHeight: import("@angular/core").WritableSignal<number | null>;
+  protected effectiveFitMode: import("@angular/core").Signal<DependencyFitMode>;
+  /** The host only gives up its configured height when the fit made it grow. */
+  protected hostHeight: import("@angular/core").Signal<string>;
+  /** `minNodeSize` expressed as the scale it forbids fitting to go below. */
+  private minFitScale;
+  constructor();
+  protected svgWidth: import("@angular/core").Signal<number>;
+  protected svgHeight: import("@angular/core").Signal<number>;
+  protected viewBox: import("@angular/core").Signal<string>;
+  protected transform: import("@angular/core").Signal<string>;
+  protected zoomLabel: import("@angular/core").Signal<number>;
+  protected selectedNode: import("@angular/core").Signal<LayoutNode | null>;
+  protected selectedDependsOn: import("@angular/core").Signal<DependencyEdgeDef[]>;
+  protected legendItems: import("@angular/core").Signal<{
+    label: string;
+    color: string;
+    dashed: boolean;
+  }[]>;
+  protected typeLegendItems: import("@angular/core").Signal<{
+    type: string;
+    color: string;
+  }[]>;
+  protected hasChildren(nodeId: string): boolean;
+  protected isCollapsed(nodeId: string): boolean;
+  protected getRelationLabel(relation: DependencyRelation): string;
+  private pruneCollapsed;
+  protected selectNode(id: string, event: Event): void;
+  protected expandNode(id: string, event: Event): void;
+  protected toggleCollapse(id: string, event: Event): void;
+  protected deselectNode(): void;
+  protected zoomIn(): void;
+  protected zoomOut(): void;
+  protected resetZoom(): void;
+  /** Centres the viewport on a node. No-op for an id that isn't laid out. */
+  focusNode(id: string): void;
+  /**
+   * Scales and centres the graph to fit the canvas, per `fitMode`. Called for you
+   * when fitting is on; public so a caller can fit on demand without it.
+   *
+   * No-op while the canvas has no size (before the first render, or in a detached
+   * / `display: none` container) — the fit observers re-run once it does.
+   */
+  fit(): void;
+  /**
+   * Restores the initial view — the fitted one under `autoFit`, otherwise the
+   * default zoom and pan.
+   */
+  resetView(): void;
+  /** Expands a collapsed node. */
+  expand(id: string): void;
+  /** Collapses a node's sub-tree. */
+  collapse(id: string): void;
+  /** Expands every collapsed node. */
+  expandAll(): void;
+  /** Collapses every node that has children. */
+  collapseAll(): void;
+  private canvasEl;
+  /**
+   * Bounding box of everything drawn, in layout units.
+   *
+   * Edge labels stand in for the edges themselves. A parent→child edge stays
+   * inside the node boxes anyway, and a bowed cross-reference puts its label just
+   * outside the apex of the bow — the only part of it that reaches past them. The
+   * label's own extent counts, as it hangs off its anchor point on one side.
+   */
+  private contentBox;
+  protected onMouseDown(event: MouseEvent): void;
+  protected onMouseMove(event: MouseEvent): void;
+  protected onMouseUp(): void;
+  protected onWheel(event: WheelEvent): void;
+  protected getNodeBg(node: LayoutNode): string;
+  protected getNodeBorder(node: LayoutNode): string;
+  protected getNodeText(node: LayoutNode): string;
+  static ɵfac: i0.ɵɵFactoryDeclaration<DependencyViewerComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<DependencyViewerComponent, "lc-dependency-viewer", never, {
+    "root": {
+      "alias": "root";
+      "required": true;
+      "isSignal": true;
+    };
+    "direction": {
+      "alias": "direction";
+      "required": false;
+      "isSignal": true;
+    };
+    "height": {
+      "alias": "height";
+      "required": false;
+      "isSignal": true;
+    };
+    "layout": {
+      "alias": "layout";
+      "required": false;
+      "isSignal": true;
+    };
+    "showToolbar": {
+      "alias": "showToolbar";
+      "required": false;
+      "isSignal": true;
+    };
+    "showEdgeLabels": {
+      "alias": "showEdgeLabels";
+      "required": false;
+      "isSignal": true;
+    };
+    "edgeWidth": {
+      "alias": "edgeWidth";
+      "required": false;
+      "isSignal": true;
+    };
+    "autoFit": {
+      "alias": "autoFit";
+      "required": false;
+      "isSignal": true;
+    };
+    "fitMode": {
+      "alias": "fitMode";
+      "required": false;
+      "isSignal": true;
+    };
+    "minNodeSize": {
+      "alias": "minNodeSize";
+      "required": false;
+      "isSignal": true;
+    };
+    "interactive": {
+      "alias": "interactive";
+      "required": false;
+      "isSignal": true;
+    };
+    "anchorNodeId": {
+      "alias": "anchorNodeId";
+      "required": false;
+      "isSignal": true;
+    };
+    "typeColors": {
+      "alias": "typeColors";
+      "required": false;
+      "isSignal": true;
+    };
+    "hiddenRelations": {
+      "alias": "hiddenRelations";
+      "required": false;
+      "isSignal": true;
+    };
+    "hiddenTypes": {
+      "alias": "hiddenTypes";
+      "required": false;
+      "isSignal": true;
+    };
+    "zoomInLabel": {
+      "alias": "zoomInLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "zoomOutLabel": {
+      "alias": "zoomOutLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "resetZoomLabel": {
+      "alias": "resetZoomLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "depthLabel": {
+      "alias": "depthLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "childrenLabel": {
+      "alias": "childrenLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "dependsOnLabel": {
+      "alias": "dependsOnLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "dependenciesLabel": {
+      "alias": "dependenciesLabel";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "nodeSelect": "nodeSelect";
+    "nodeExpand": "nodeExpand";
+  }, never, never, true, never>;
+}
+export {};