@inkra/react 0.10.0 → 0.12.0

package/README.md

@@ -17,6 +17,41 @@ Inkra components require a React client boundary. Next.js and React Server Compo
 
 ## Usage
 
+### Dependency Graphs
+
+`DependencyGraph.Root` lays out skill trees, technology trees and other directed
+dependency graphs without manual node positions:
+
+```tsx
+import '@inkra/react/styles.css';
+import { DependencyGraph } from '@inkra/react';
+
+<DependencyGraph.Root
+  nodes={[
+    { id: 'basics', label: 'Basics', status: 'completed' },
+    { id: 'practice', label: 'Practice', status: 'available' },
+    { id: 'mastery', label: 'Mastery', status: 'locked' },
+  ]}
+  edges={[
+    { id: 'basics-practice', source: 'basics', target: 'practice' },
+    { id: 'practice-mastery', source: 'practice', target: 'mastery' },
+  ]}
+/>;
+```
+
+The application owns unlock rules and progress. Nodes support icon, content,
+actions and footer regions; `nodeVariant="icon"` shows compact icon nodes.
+`renderNode` owns the complete node appearance, including frameless images.
+Its `renderSurface` helper can wrap both faces of a Flip card so the border and
+paper rotate together. Node/edge `sourceAnchor` and `targetAnchor` accept
+normalized `{ x, y, position? }` coordinates; edge settings override node defaults.
+
+Configure individual viewport actions with
+`controls={{ zoomIn: true, zoomOut: false, fitView: true }}`, or hide the toolbar
+with `controls={false}`. `extraControls` appends custom buttons and can receive
+the viewport API. The standalone entry is `@inkra/react/dependency-graph`;
+its optional stylesheet is `@inkra/react/styles/dependency-graph.css`.
+
 ### Guided And Asynchronous Experiences
 
 `Guide.Root`, `Guide.Trigger` and `Guide.Step` compose a targeted walkthrough.
@@ -487,16 +522,37 @@ shrinking values and sign changes expand or collapse the affected columns.
 Grouping, signs, currency and compact units remain formatted text, not digit
 reels. `rollDirection="auto"` rolls up for increasing values and down for
 decreasing values; `up` or `down` fixes the direction. `duration` and `easing`
-apply to both modes. The default `animation="count"` retains value interpolation.
+apply to all modes. The default `animation="count"` retains value interpolation.
 `renderValue` takes precedence over the built-in reels. Changing the formatting
 or animation mode settles immediately, as do disabled/reduced motion, invalid
 durations, and transitions with more than 128 formatted tokens. Exact strings
-and bigint values retain their original precision in either mode.
+and bigint values retain their original precision in every mode.
 
 ```tsx
 <NumberTicker value={amount} animation="roll" rollDirection="auto" duration={650} />
 ```
 
+Use `animation="morph"` to preserve digit identities during exact nonzero,
+same-sign multiplication or division by a power of ten. For example, `1 → 100`
+moves the existing `1` left and reveals `00` from the right; `12.34 → 123.4`
+preserves all four digits while the decimal moves. The displayed significand and
+decimal shift must agree with the exact values after formatting. Other changes,
+including carries, sign changes, unit changes and exponent notation, use
+place-aligned vertical rolling. This mode does not search for arbitrary matching
+digits or reorder repeated glyphs.
+
+Glyph widths stay fixed: motion uses position, clipping and a smooth opacity
+fade rather than stretching text. Rapid updates continue from visible positions
+and opacity. Keep the caller's container right-aligned to hold the numeric right
+edge fixed as its width changes, and allow enough space for the formatted value;
+the animation is clipped within its number area. The default duration is 420ms.
+
+```tsx
+<div style={{ display: 'flex', justifyContent: 'flex-end' }}>
+  <NumberTicker value={amount} animation="morph" duration={420} />
+</div>
+```
+
 Set `compact` to follow `locale` (Chinese units for `zh`, English units otherwise),
 or use `compact="en"` / `compact="zh"` to select a unit table explicitly.
 English uses this library's short-scale suffix convention: K, M, B, T, Qa, Qi,
@@ -570,7 +626,10 @@ technology; decorative affixes are not announced twice.
 
 `Log` renders caller-ordered records with stable ids, optional level filters and
 pause/follow controls. It follows only append updates while the viewport remains
-near the bottom. The named scroll region supports Home/End and intentionally is
+near the bottom. When scrolled away or paused, a localized icon button floats
+at the viewport's bottom end corner without adding a footer row. Clicking it
+returns focus to the scroll region and resumes following or jumps to the latest
+record. The named scroll region supports Home/End and intentionally is
 not a live region, so a long stream is not repeatedly announced. Log does not
 provide persistence, virtualization or transport.
 

package/dist/dependency-graph/index.d.ts

@@ -0,0 +1,47 @@
+import { type HTMLAttributes, type ReactElement, type ReactNode, type RefAttributes } from 'react';
+import { type NodeGraphRootProps, type NodeGraphRef } from '../node-graph/index.js';
+import { layoutDependencyGraph, type DependencyGraphNode, type DependencyGraphEdge, type DependencyGraphStatus, type DependencyGraphDirection } from './model.js';
+export * from './model.js';
+export type DependencyGraphRef = NodeGraphRef;
+export interface DependencyGraphNodeRenderState {
+    selected: boolean;
+    highlighted: boolean;
+    activate: () => void;
+    /** Wrap each animated face so its paper, border and selection move together. */
+    renderSurface: (children: ReactNode) => ReactElement;
+}
+export interface DependencyGraphRootProps<Data = unknown> extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'> {
+    nodes: DependencyGraphNode<Data>[];
+    edges: DependencyGraphEdge[];
+    direction?: DependencyGraphDirection;
+    selectedId?: string | null;
+    defaultSelectedId?: string | null;
+    onSelectedIdChange?: (id: string | null) => void;
+    /** Activation does not infer or mutate business unlock rules. */
+    onNodeActivate?: (node: DependencyGraphNode<Data>) => void;
+    highlight?: 'ancestors' | 'descendants' | 'both' | 'none';
+    nodeWidth?: number;
+    nodeHeight?: number;
+    rankGap?: number;
+    nodeGap?: number;
+    nodeVariant?: 'card' | 'icon';
+    renderNode?: (node: DependencyGraphNode<Data>, state: DependencyGraphNodeRenderState) => ReactNode;
+    statusLabels?: Partial<Record<DependencyGraphStatus, string>>;
+    onIssues?: (issues: ReturnType<typeof layoutDependencyGraph>['issues']) => void;
+    controls?: NodeGraphRootProps['controls'];
+    extraControls?: NodeGraphRootProps['extraControls'];
+    fitView?: boolean;
+    minZoom?: number;
+    maxZoom?: number;
+    panOnDrag?: boolean;
+    zoomOnScroll?: boolean;
+    zoomOnPinch?: boolean;
+    onlyRenderVisibleElements?: boolean;
+    hideAttribution?: boolean;
+    emptyState?: ReactNode;
+    controlLabels?: NodeGraphRootProps['controlLabels'];
+}
+export declare const DependencyGraphRoot: <Data = unknown>(props: DependencyGraphRootProps<Data> & RefAttributes<DependencyGraphRef>) => ReactElement;
+export declare const DependencyGraph: {
+    Root: <Data = unknown>(props: DependencyGraphRootProps<Data> & RefAttributes<DependencyGraphRef>) => ReactElement;
+};

package/dist/dependency-graph/index.js

@@ -0,0 +1,177 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { Handle, Position, useNodesInitialized, useReactFlow } from '@xyflow/react';
+import { NodeGraph } from '../node-graph/index.js';
+import { PencilSurface } from '../PencilSurface.js';
+import { PencilText } from '../PencilText.js';
+import { PencilIcon } from '../PencilIcon.js';
+import { useInkraLocale } from '../i18n/index.js';
+import { layoutDependencyGraph, getDependencyGraphHighlight } from './model.js';
+export * from './model.js';
+function NodeFrame({ bare, seed, variant, ...props }) {
+    return bare ? _jsx("div", { ...props }) : _jsx(PencilSurface, { ...props, seed: seed, variant: variant });
+}
+function NodeText({ children, className, ellipsis }) {
+    return typeof children === 'string' || typeof children === 'number'
+        ? _jsx(PencilText, { className: className, ellipsis: ellipsis, children: String(children) })
+        : _jsx("span", { className: className, children: children });
+}
+// The arrow follows the final tangent of the very same curve drawn by NodeGraph.
+// Both the open and filled silhouettes remain actual pencil geometry.
+function DirectionArrow({ path }) {
+    const measure = useRef(null);
+    const [tip, setTip] = useState(null);
+    useLayoutEffect(() => {
+        const node = measure.current;
+        if (!node)
+            return;
+        try {
+            const length = node.getTotalLength();
+            if (!Number.isFinite(length) || length < 1) {
+                setTip(null);
+                return;
+            }
+            const end = node.getPointAtLength(length);
+            const before = node.getPointAtLength(Math.max(0, length - 4));
+            const angle = Math.atan2(end.y - before.y, end.x - before.x);
+            if (![end.x, end.y, angle].every(Number.isFinite)) {
+                setTip(null);
+                return;
+            }
+            setTip({ x: end.x - Math.cos(angle) * 7, y: end.y - Math.sin(angle) * 7, angle: angle * 180 / Math.PI });
+        }
+        catch {
+            setTip(null);
+        }
+    }, [path]);
+    return _jsxs("g", { "aria-hidden": "true", pointerEvents: "none", children: [_jsx("path", { ref: measure, d: path, fill: "none", stroke: "none" }), tip && _jsx("g", { transform: `translate(${tip.x} ${tip.y}) rotate(${tip.angle})`, children: _jsx("foreignObject", { x: -10, y: -10, width: 20, height: 20, overflow: "visible", children: _jsx(PencilIcon, { decorative: true, size: 20, sourceSize: 40, strokeWidth: 1.8, breaks: 0, paths: [{ d: 'M6 8L34 20L6 32' }], filledPaths: [{ d: 'M6 6L34 20L6 34L4 30L24 20L4 10Z' }], seed: "dependency-direction" }) }) })] });
+}
+function anchorFraction(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : fallback;
+}
+function DependencyViewport({ layoutKey, enabled, onFit }) {
+    const initialized = useNodesInitialized();
+    const { fitView } = useReactFlow();
+    const fitted = useRef(null);
+    useEffect(() => {
+        if (!enabled || !initialized || fitted.current === layoutKey)
+            return;
+        fitted.current = layoutKey;
+        let cancelled = false;
+        void fitView().then(success => { if (success && !cancelled)
+            onFit(layoutKey); });
+        return () => { cancelled = true; if (fitted.current === layoutKey)
+            fitted.current = null; };
+    }, [enabled, initialized, layoutKey, fitView, onFit]);
+    return null;
+}
+function DependencyGraphRootInner(props, ref) {
+    const { t } = useInkraLocale();
+    const { nodes, edges, direction = 'LR', selectedId, defaultSelectedId = null, onSelectedIdChange, onNodeActivate, highlight = 'ancestors', nodeVariant = 'card', nodeWidth = nodeVariant === 'icon' ? 80 : 200, nodeHeight = nodeVariant === 'icon' ? 80 : 104, rankGap = 96, nodeGap = 40, renderNode, statusLabels, onIssues, className, fitView = true, onlyRenderVisibleElements = false, hideAttribution = true, ...rest } = props;
+    const [internalSelected, setInternalSelected] = useState(defaultSelectedId);
+    const [fittedLayout, setFittedLayout] = useState(null);
+    const graphRef = useRef(null);
+    useImperativeHandle(ref, () => ({
+        fitView: options => graphRef.current?.fitView(options) ?? Promise.resolve(false),
+        zoomIn: () => graphRef.current?.zoomIn() ?? Promise.resolve(false),
+        zoomOut: () => graphRef.current?.zoomOut() ?? Promise.resolve(false),
+        getViewport: () => graphRef.current?.getViewport() ?? { x: 0, y: 0, zoom: 1 },
+    }), []);
+    const candidate = selectedId === undefined ? internalSelected : selectedId;
+    const activeId = nodes.some(node => node.id === candidate) ? candidate : null;
+    const layout = useMemo(() => layoutDependencyGraph(nodes, edges, { direction, nodeWidth, nodeHeight, rankGap, nodeGap }), [nodes, edges, direction, nodeWidth, nodeHeight, rankGap, nodeGap]);
+    const issuesCallback = useRef(onIssues);
+    issuesCallback.current = onIssues;
+    useEffect(() => { issuesCallback.current?.(layout.issues); }, [layout.issues]);
+    const layoutKey = layout.nodes.map(node => `${node.id}:${node.position.x}:${node.position.y}:${node.width}:${node.height}`).join('|');
+    const highlighted = useMemo(() => getDependencyGraphHighlight(nodes, layout.edges, activeId, highlight), [nodes, layout.edges, activeId, highlight]);
+    const graphNodes = useMemo(() => {
+        const byId = new Map();
+        nodes.forEach(node => { if (!byId.has(node.id))
+            byId.set(node.id, node); });
+        const sourcePosition = ({ LR: Position.Right, RL: Position.Left, TB: Position.Bottom, BT: Position.Top })[direction];
+        const targetPosition = ({ LR: Position.Left, RL: Position.Right, TB: Position.Top, BT: Position.Bottom })[direction];
+        const positions = new Map(layout.nodes.map(node => [node.id, node]));
+        const incoming = new Map(layout.nodes.map(node => [node.id, []]));
+        const outgoing = new Map(layout.nodes.map(node => [node.id, []]));
+        layout.edges.forEach(edge => { incoming.get(edge.target).push(edge); outgoing.get(edge.source).push(edge); });
+        const crossAxis = direction === 'LR' || direction === 'RL' ? 'y' : 'x';
+        return layout.nodes.map(positioned => {
+            const original = byId.get(positioned.id);
+            const anchors = [];
+            for (const type of ['source', 'target']) {
+                const position = type === 'source' ? sourcePosition : targetPosition;
+                const connected = [...(type === 'source' ? outgoing : incoming).get(positioned.id)];
+                const neighbor = (edge) => positions.get(type === 'source' ? edge.target : edge.source).position[crossAxis];
+                connected.sort((a, b) => neighbor(a) - neighbor(b));
+                connected.forEach((edge, index) => {
+                    const fraction = (index + 1) / (connected.length + 1);
+                    const key = type === 'source' ? 'sourceAnchor' : 'targetAnchor';
+                    const custom = edge[key] ?? original[key];
+                    const side = custom?.position;
+                    const anchorPosition = side === 'left' || side === 'right' || side === 'top' || side === 'bottom'
+                        ? side : position;
+                    const defaultX = position === Position.Left ? 0 : position === Position.Right ? 1 : fraction;
+                    const defaultY = position === Position.Top ? 0 : position === Position.Bottom ? 1 : fraction;
+                    anchors.push({ id: `${type}-${edge.id}`, type, position: anchorPosition,
+                        x: positioned.width * anchorFraction(custom?.x, defaultX),
+                        y: positioned.height * anchorFraction(custom?.y, defaultY) });
+                });
+            }
+            return { ...positioned, focusable: false,
+                measured: { width: positioned.width, height: positioned.height },
+                handles: anchors.map(anchor => ({ ...anchor, width: 0, height: 0 })),
+                sourcePosition, targetPosition, data: {
+                    label: original.label, original, anchors,
+                } };
+        });
+    }, [nodes, layout.nodes, layout.edges, direction]);
+    const graphEdges = useMemo(() => layout.edges.map(edge => ({ ...edge, focusable: false, selectable: false,
+        sourceHandle: `source-${edge.id}`, targetHandle: `target-${edge.id}`, data: { highlighted: highlighted.edgeIds.has(edge.id) } })), [layout.edges, highlighted]);
+    const renderGraphNode = ({ id, data }) => {
+        const node = data.original;
+        const selected = id === activeId;
+        const related = highlighted.nodeIds.has(id);
+        const status = node.status;
+        const label = typeof node.label === 'string' || typeof node.label === 'number' ? String(node.label) : id;
+        const activate = () => {
+            if (node.disabled)
+                return;
+            if (selectedId === undefined)
+                setInternalSelected(id);
+            onSelectedIdChange?.(id);
+            onNodeActivate?.(node);
+        };
+        const decoration = _jsxs(_Fragment, { children: [(selected || related) && _jsx(PencilSurface, { as: "span", "aria-hidden": "true", variant: "outline", className: "inkra-dependency-graph__highlight", seed: `dependency-outline-${id}` }), _jsx(PencilSurface, { as: "span", "aria-hidden": "true", variant: "outline", className: "inkra-dependency-graph__focus", seed: `dependency-focus-${id}` })] });
+        const renderSurface = (children) => _jsxs(PencilSurface, { variant: selected ? 'action' : 'paper', seed: `dependency-${id}`, className: "inkra-dependency-graph__card inkra-dependency-graph__card--custom", children: [decoration, children] });
+        return _jsxs("div", { className: "inkra-dependency-graph__node", "data-status": status, "data-selected": selected || undefined, "data-highlighted": related || undefined, "data-disabled": node.disabled || undefined, "data-dimmed": activeId !== null && highlight !== 'none' && !related && !selected || undefined, children: [!renderNode && nodeVariant === 'icon'
+                    ? _jsxs(PencilSurface, { as: "button", type: "button", variant: selected ? 'action' : 'paper', className: "inkra-dependency-graph__icon-button nodrag nopan", disabled: node.disabled, "aria-label": label, title: label, "aria-pressed": selected, seed: `dependency-${id}`, onClick: activate, children: [decoration, node.icon ?? _jsx(NodeText, { children: label.slice(0, 1) })] })
+                    : _jsxs(NodeFrame, { bare: Boolean(renderNode), variant: selected ? 'action' : 'paper', seed: `dependency-${id}`, className: `inkra-dependency-graph__card nodrag nopan${renderNode ? ' inkra-dependency-graph__card--custom' : ''}`, role: "group", "aria-label": label, "aria-disabled": node.disabled || undefined, tabIndex: renderNode && !node.disabled ? 0 : undefined, onClick: event => {
+                            if (!(event.target instanceof Element) || event.target.closest('button,a,input,select,textarea,[role="button"],[contenteditable="true"]'))
+                                return;
+                            activate();
+                        }, onKeyDown: event => {
+                            if (event.target === event.currentTarget && (event.key === 'Enter' || event.key === ' ')) {
+                                event.preventDefault();
+                                activate();
+                            }
+                        }, children: [!renderNode && decoration, renderNode ? renderNode(node, { selected, highlighted: related, activate, renderSurface }) : _jsxs(_Fragment, { children: [_jsxs("div", { className: "inkra-dependency-graph__header", children: [node.icon != null && _jsx("span", { className: "inkra-dependency-graph__icon", "aria-hidden": "true", children: node.icon }), _jsx("button", { type: "button", className: "inkra-dependency-graph__title", disabled: node.disabled, "aria-pressed": selected, onClick: activate, children: _jsx(NodeText, { ellipsis: true, children: node.label }) }), node.actions != null && _jsx("div", { className: "inkra-dependency-graph__actions", children: node.actions })] }), (node.content ?? node.description) != null && _jsx("div", { className: "inkra-dependency-graph__body nowheel", children: typeof (node.content ?? node.description) === 'string' || typeof (node.content ?? node.description) === 'number'
+                                            ? _jsx(NodeText, { children: node.content ?? node.description }) : node.content ?? node.description }), status && _jsx(PencilText, { className: "inkra-dependency-graph__status", children: statusLabels?.[status] ?? t(`dependency.${status}`) }), node.footer != null && _jsx("div", { className: "inkra-dependency-graph__footer", children: node.footer })] })] }), data.anchors.map(anchor => _jsx(Handle, { id: anchor.id, type: anchor.type, position: anchor.position, isConnectable: false, "aria-hidden": "true", className: "inkra-dependency-graph__anchor", style: { left: anchor.x, top: anchor.y } }, anchor.id)), id === layout.nodes[0]?.id && _jsx(DependencyViewport, { layoutKey: layoutKey, enabled: fitView, onFit: setFittedLayout })] });
+    };
+    const renderGraphEdge = ({ id, edge, path, labelX, labelY }) => {
+        const related = Boolean(edge.data?.highlighted);
+        return _jsxs("g", { className: "inkra-dependency-graph__edge", "data-highlighted": related || undefined, "data-dimmed": activeId !== null && highlight !== 'none' && !related || undefined, children: [_jsx(NodeGraph.Edge, { id: id, path: path, label: typeof edge.label === 'string' || typeof edge.label === 'number' ? _jsx(PencilText, { children: String(edge.label) }) : edge.label, labelX: labelX, labelY: labelY, interactionWidth: 0, className: related ? 'inkra-dependency-graph__edge--highlighted' : undefined }), _jsx(DirectionArrow, { path: path })] });
+    };
+    return _jsx(NodeGraph.Root, { ...rest, ref: graphRef, nodes: graphNodes, edges: graphEdges, readOnly: true, fitView: false, hideAttribution: hideAttribution, onlyRenderVisibleElements: onlyRenderVisibleElements && (!fitView || fittedLayout === layoutKey), onKeyDown: event => {
+            props.onKeyDown?.(event);
+            if (event.key === 'Escape' && activeId !== null && !event.defaultPrevented) {
+                event.preventDefault();
+                event.stopPropagation();
+                if (selectedId === undefined)
+                    setInternalSelected(null);
+                onSelectedIdChange?.(null);
+            }
+        }, "aria-label": props['aria-label'] ?? t('dependency.label'), className: ['inkra-dependency-graph', className].filter(Boolean).join(' '), renderNode: renderGraphNode, renderEdge: renderGraphEdge });
+}
+export const DependencyGraphRoot = forwardRef(DependencyGraphRootInner);
+export const DependencyGraph = { Root: DependencyGraphRoot };

package/dist/dependency-graph/model.d.ts

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react';
+export type DependencyGraphDirection = 'LR' | 'RL' | 'TB' | 'BT';
+export type DependencyGraphStatus = 'locked' | 'available' | 'active' | 'completed';
+/** A point in the node's local box. Coordinates are fractions clamped to 0..1.
+ * position controls the curve tangent; explicit points do not rotate with direction.
+ */
+export interface DependencyGraphAnchor {
+    x: number;
+    y: number;
+    position?: 'left' | 'right' | 'top' | 'bottom';
+}
+export interface DependencyGraphNode<Data = unknown> {
+    id: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    content?: ReactNode;
+    actions?: ReactNode;
+    footer?: ReactNode;
+    description?: ReactNode;
+    status?: DependencyGraphStatus;
+    disabled?: boolean;
+    sourceAnchor?: DependencyGraphAnchor;
+    targetAnchor?: DependencyGraphAnchor;
+    data?: Data;
+}
+export interface DependencyGraphEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: ReactNode;
+    /** Overrides the source node's default anchor for this edge. */
+    sourceAnchor?: DependencyGraphAnchor;
+    /** Overrides the target node's default anchor for this edge. */
+    targetAnchor?: DependencyGraphAnchor;
+}
+export interface DependencyGraphIssue {
+    type: 'duplicate-node' | 'duplicate-edge' | 'missing-node' | 'cycle';
+    ids: string[];
+}
+export interface DependencyGraphLayoutOptions {
+    direction?: DependencyGraphDirection;
+    nodeWidth?: number;
+    nodeHeight?: number;
+    rankGap?: number;
+    nodeGap?: number;
+}
+/** Stable input order within each rank; edge direction is source prerequisite → target.
+ * Duplicate IDs keep their first entry. Missing endpoints and intra-cycle edges
+ * are omitted and reported through issues; downstream dependencies remain intact.
+ */
+export declare function layoutDependencyGraph<Data>(nodes: readonly DependencyGraphNode<Data>[], inputEdges: readonly DependencyGraphEdge[], options?: DependencyGraphLayoutOptions): {
+    nodes: {
+        id: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        width: number;
+        height: number;
+    }[];
+    edges: DependencyGraphEdge[];
+    issues: DependencyGraphIssue[];
+};
+/** Traversal is independent of layout and terminates even for invalid cyclic input. */
+export declare function getDependencyGraphHighlight<Data>(nodes: readonly DependencyGraphNode<Data>[], edges: readonly DependencyGraphEdge[], selectedId: string | null, mode: 'ancestors' | 'descendants' | 'both' | 'none'): {
+    nodeIds: Set<string>;
+    edgeIds: Set<string>;
+};

package/dist/dependency-graph/model.js

@@ -0,0 +1,198 @@
+function normalize(nodes, edges) {
+    const unique = new Map();
+    const issues = [];
+    for (const node of nodes) {
+        if (unique.has(node.id))
+            issues.push({ type: 'duplicate-node', ids: [node.id] });
+        else
+            unique.set(node.id, node);
+    }
+    const edgeIds = new Set();
+    const valid = [];
+    for (const edge of edges) {
+        if (edgeIds.has(edge.id)) {
+            issues.push({ type: 'duplicate-edge', ids: [edge.id] });
+            continue;
+        }
+        edgeIds.add(edge.id);
+        const missing = [edge.source, edge.target].filter(id => !unique.has(id));
+        if (missing.length)
+            issues.push({ type: 'missing-node', ids: [edge.id, ...new Set(missing)] });
+        else
+            valid.push(edge);
+    }
+    return { ids: [...unique.keys()], edges: valid, issues };
+}
+function adjacency(ids, edges, reverse = false) {
+    const result = new Map(ids.map(id => [id, []]));
+    for (const edge of edges)
+        result.get(reverse ? edge.target : edge.source).push(reverse ? edge.source : edge.target);
+    return result;
+}
+// Iterative Kosaraju traversal avoids a call-stack limit on long dependency chains.
+function components(ids, edges) {
+    const forward = adjacency(ids, edges);
+    const backward = adjacency(ids, edges, true);
+    const visited = new Set();
+    const finished = [];
+    for (const id of ids) {
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        const stack = [{ id, next: 0 }];
+        while (stack.length) {
+            const frame = stack[stack.length - 1];
+            const neighbors = forward.get(frame.id);
+            if (frame.next >= neighbors.length) {
+                finished.push(frame.id);
+                stack.pop();
+            }
+            else {
+                const next = neighbors[frame.next++];
+                if (!visited.has(next)) {
+                    visited.add(next);
+                    stack.push({ id: next, next: 0 });
+                }
+            }
+        }
+    }
+    const membership = new Map();
+    const groups = [];
+    for (let index = finished.length - 1; index >= 0; index--) {
+        const id = finished[index];
+        if (membership.has(id))
+            continue;
+        const group = groups.length;
+        const stack = [id];
+        membership.set(id, group);
+        const members = [];
+        while (stack.length) {
+            const current = stack.pop();
+            members.push(current);
+            for (const previous of backward.get(current)) {
+                if (membership.has(previous))
+                    continue;
+                membership.set(previous, group);
+                stack.push(previous);
+            }
+        }
+        groups.push(members);
+    }
+    return { membership, groups };
+}
+function dimension(value, fallback, minimum) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.max(minimum, Math.min(2000, value)) : fallback;
+}
+/** Stable input order within each rank; edge direction is source prerequisite → target.
+ * Duplicate IDs keep their first entry. Missing endpoints and intra-cycle edges
+ * are omitted and reported through issues; downstream dependencies remain intact.
+ */
+export function layoutDependencyGraph(nodes, inputEdges, options = {}) {
+    const normalized = normalize(nodes, inputEdges);
+    const { ids, issues } = normalized;
+    const { membership, groups } = components(ids, normalized.edges);
+    const cyclic = new Set();
+    for (const edge of normalized.edges) {
+        const group = membership.get(edge.source);
+        if (group === membership.get(edge.target) && (groups[group].length > 1 || edge.source === edge.target))
+            cyclic.add(group);
+    }
+    // A downstream node is not itself cyclic. Report only actual SCC members.
+    const cycleMembers = new Map();
+    for (const id of ids) {
+        const group = membership.get(id);
+        if (!cyclic.has(group))
+            continue;
+        const members = cycleMembers.get(group) ?? [];
+        members.push(id);
+        cycleMembers.set(group, members);
+    }
+    for (const group of cyclic)
+        issues.push({ type: 'cycle', ids: cycleMembers.get(group) });
+    const edges = normalized.edges.filter(edge => {
+        const group = membership.get(edge.source);
+        return !cyclic.has(group) || membership.get(edge.target) !== group;
+    });
+    const children = adjacency(ids, edges);
+    const indegree = new Map(ids.map(id => [id, 0]));
+    const rank = new Map(ids.map(id => [id, 0]));
+    for (const edge of edges)
+        indegree.set(edge.target, indegree.get(edge.target) + 1);
+    const queue = ids.filter(id => indegree.get(id) === 0);
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const id = queue[cursor];
+        for (const child of children.get(id)) {
+            rank.set(child, Math.max(rank.get(child), rank.get(id) + 1));
+            const remaining = indegree.get(child) - 1;
+            indegree.set(child, remaining);
+            if (!remaining)
+                queue.push(child);
+        }
+    }
+    const layers = new Map();
+    for (const id of ids) {
+        const level = rank.get(id);
+        const layer = layers.get(level) ?? [];
+        layer.push(id);
+        layers.set(level, layer);
+    }
+    const width = dimension(options.nodeWidth, 200, 80);
+    const height = dimension(options.nodeHeight, 104, 44);
+    const rankGap = dimension(options.rankGap, 96, 0);
+    const nodeGap = dimension(options.nodeGap, 40, 0);
+    const direction = options.direction ?? 'LR';
+    const horizontal = direction === 'LR' || direction === 'RL';
+    let maxRank = 0;
+    let maxCount = 0;
+    for (const [level, layer] of layers) {
+        maxRank = Math.max(maxRank, level);
+        maxCount = Math.max(maxCount, layer.length);
+    }
+    const positions = new Map();
+    for (const [level, layer] of layers) {
+        const mainLevel = direction === 'RL' || direction === 'BT' ? maxRank - level : level;
+        const main = mainLevel * ((horizontal ? width : height) + rankGap);
+        const step = (horizontal ? height : width) + nodeGap;
+        const offset = (maxCount - layer.length) * step / 2;
+        layer.forEach((id, index) => {
+            const cross = offset + index * step;
+            positions.set(id, horizontal ? { x: main, y: cross } : { x: cross, y: main });
+        });
+    }
+    return { nodes: ids.map(id => ({ id, position: positions.get(id), width, height })), edges, issues };
+}
+/** Traversal is independent of layout and terminates even for invalid cyclic input. */
+export function getDependencyGraphHighlight(nodes, edges, selectedId, mode) {
+    const valid = normalize(nodes, edges);
+    const nodeIds = new Set();
+    const edgeIds = new Set();
+    if (selectedId === null || !valid.ids.includes(selectedId))
+        return { nodeIds, edgeIds };
+    nodeIds.add(selectedId);
+    if (mode === 'none')
+        return { nodeIds, edgeIds };
+    const walk = (reverse) => {
+        const adjacent = new Map(valid.ids.map(id => [id, []]));
+        for (const edge of valid.edges)
+            adjacent.get(reverse ? edge.target : edge.source).push(edge);
+        const visited = new Set([selectedId]);
+        const stack = [selectedId];
+        while (stack.length) {
+            const current = stack.pop();
+            for (const edge of adjacent.get(current)) {
+                const next = reverse ? edge.source : edge.target;
+                edgeIds.add(edge.id);
+                nodeIds.add(next);
+                if (!visited.has(next)) {
+                    visited.add(next);
+                    stack.push(next);
+                }
+            }
+        }
+    };
+    if (mode === 'ancestors' || mode === 'both')
+        walk(true);
+    if (mode === 'descendants' || mode === 'both')
+        walk(false);
+    return { nodeIds, edgeIds };
+}