@startdownnotez404/ui 1.0.0 → 1.3.5

package/dist/flowMap.d.ts

@@ -0,0 +1,353 @@
+import * as react from 'react';
+import react__default, { CSSProperties, MouseEventHandler, ReactNode } from 'react';
+import * as _xyflow_react from '@xyflow/react';
+import { Position, Node, Edge, NodeChange, EdgeChange, NodeProps, EdgeProps, FitViewOptions, NodeTypes, EdgeTypes, MiniMapProps, ControlProps, HandleProps } from '@xyflow/react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type FlowMapFitViewAlign = 'center' | 'top';
+
+declare const HANDLER_IDs: {
+    readonly source: "source";
+    readonly target: "target";
+    readonly loopSource: "loop-source";
+    readonly loopTarget: "loop-target";
+};
+/** @deprecated Prefer resolveHandlePositions — kept as RIGHT defaults for compat. */
+declare const HANDLE_POSITIONs: {
+    readonly source: Position.Right;
+    readonly target: Position.Left;
+    readonly loopSource: Position.Bottom;
+    readonly loopTarget: Position.Bottom;
+};
+type FlowMapLayoutDirection = 'RIGHT' | 'DOWN' | 'LEFT' | 'UP';
+type FlowMapHandleSide = 'top' | 'right' | 'bottom' | 'left' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight';
+type FlowMapHandleAnchor = {
+    side: FlowMapHandleSide;
+    position: Position;
+    style: CSSProperties;
+};
+type FlowMapResolvedHandlePositions = {
+    target: FlowMapHandleAnchor;
+    source: FlowMapHandleAnchor;
+    loopTarget: FlowMapHandleAnchor;
+    loopSource: FlowMapHandleAnchor;
+};
+/**
+ * Map a named side/corner (+ optional offset along the edge) to RF Position + style.
+ * Top/Bottom offsets use `left`; Left/Right offsets use `top`.
+ */
+declare const resolveHandleAnchor: (side: FlowMapHandleSide, offset?: string | number) => FlowMapHandleAnchor;
+/** Primary + loop handle anchors for a layout direction. */
+declare const resolveHandlePositions: (direction?: FlowMapLayoutDirection) => FlowMapResolvedHandlePositions;
+
+type FlowMapHandlesSlotProps = {
+    kind: 'group' | 'default';
+    layoutDirection: FlowMapLayoutDirection;
+    handles: FlowMapResolvedHandlePositions;
+    handlerIds: typeof HANDLER_IDs;
+};
+declare const FLOW_MAP_GROUP_NODE_TYPE = "group-node";
+interface FlowMapNodeData extends Record<string, unknown> {
+    label?: string;
+}
+interface FlowMapGroupNodeData extends FlowMapNodeData {
+    description?: string;
+    collapsible?: boolean;
+    collapsed?: boolean;
+    collapsedHeight?: number | string;
+    descendantCount?: number;
+    onCollapseToggle?: () => void;
+    onCollapseChange?: (collapsed: boolean, groupId: string) => void;
+}
+interface FlowMapGroupToggleSlotProps {
+    groupId: string;
+    data: FlowMapGroupNodeData;
+    collapsed: boolean;
+    label: string;
+    title: string;
+    className: string;
+    onMouseDown: MouseEventHandler<HTMLElement>;
+    onClick: MouseEventHandler<HTMLElement>;
+}
+type FlowMapNode = Node<FlowMapNodeData>;
+type FlowMapEdge = Edge;
+interface FlowTreeGroup {
+    id: string;
+    /**
+     * Optional custom group renderer type.
+     * Defaults to `FLOW_MAP_GROUP_NODE_TYPE`.
+     */
+    type?: string;
+    /**
+     * Group node data merged into the derived container node.
+     */
+    data?: FlowMapGroupNodeData;
+    /**
+     * Optional sizing/styling for the derived group node.
+     * Width/height are respected when present.
+     */
+    style?: FlowMapNode['style'];
+}
+interface FlowTreeNode {
+    id: string;
+    type?: string;
+    data?: Record<string, unknown>;
+    style?: FlowMapNode['style'];
+    children?: FlowTreeNode[];
+    edgeLabel?: string;
+    /**
+     * Assign this node to a derived group container in tree mode.
+     * Repeated group definitions with the same `id` are merged shallowly.
+     */
+    group?: string | FlowTreeGroup;
+    /**
+     * Create extra connections to existing nodes (e.g. for loops/jumps).
+     * Provide the target Node ID(s).
+     */
+    connectTo?: string[];
+}
+interface FlowMapSlots {
+    /**
+     * Override FlowMap's standard node renderer (`custom-node`).
+     */
+    defaultNode?: NodeTypes[string];
+    /**
+     * Override how grouped parent nodes render.
+     *
+     * Applied to FlowMap's `FLOW_MAP_GROUP_NODE_TYPE` and React Flow's built-in
+     * `group` node type when used through FlowMap.
+     */
+    groupNode?: NodeTypes[string];
+    /**
+     * Override the expand/collapse control used by FlowMap's default group renderer.
+     * Ignored when `slots.groupNode` replaces the entire group node renderer.
+     */
+    groupToggle?: (props: FlowMapGroupToggleSlotProps) => ReactNode;
+    /**
+     * Override FlowMap's default edge renderer (`custom-edge`).
+     */
+    edge?: EdgeTypes[string];
+    /**
+     * Replace the built-in Handle set on group shells and default nodes.
+     * Compose exported helpers such as `<LeftHandle offset="3px" />`.
+     */
+    handles?: (props: FlowMapHandlesSlotProps) => ReactNode;
+}
+interface FlowMapProps {
+    /**
+     * Raw React Flow nodes.
+     *
+     * Grouped flows are supported by rendering a parent node with
+     * `type: FLOW_MAP_GROUP_NODE_TYPE` or React Flow's built-in `group` type and
+     * assigning `parentId` on child nodes. Grouped flows opt out of ELK
+     * auto-layout because child positions are relative to the parent node.
+     */
+    nodes?: FlowMapNode[];
+    edges?: FlowMapEdge[];
+    /**
+     * Controlled collapsed state for group nodes, keyed by group id.
+     * When omitted, FlowMap manages collapse state internally using each group's
+     * `data.collapsed` value as the initial default.
+     */
+    collapsedGroups?: Record<string, boolean>;
+    /**
+     * Called when FlowMap requests a collapsed state change.
+     * Useful with `collapsedGroups` for controlled collapse behavior.
+     */
+    onCollapsedGroupsChange?: (collapsedGroups: Record<string, boolean>) => void;
+    /**
+     * Provide a tree structure instead of nodes/edges.
+     * If provided, nodes and edges props are ignored.
+     */
+    tree?: FlowTreeNode;
+    onNodesChange?: (changes: NodeChange<FlowMapNode>[]) => void;
+    onEdgesChange?: (changes: EdgeChange<FlowMapEdge>[]) => void;
+    nodeTypes?: Record<string, React.ComponentType<NodeProps>>;
+    edgeTypes?: Record<string, React.ComponentType<EdgeProps>>;
+    className?: string;
+    colors?: {
+        highlight?: string;
+        loop?: string;
+        edge?: string;
+        nodeBg?: string;
+        nodeColor?: string;
+        nodeBorder?: string;
+    };
+    showMiniMap?: boolean;
+    showControls?: boolean;
+    /**
+     * Controls whether nodes can be dragged.
+     * Defaults to true.
+     */
+    nodesDraggable?: boolean;
+    /**
+     * Opacity scalar for the Flow background pattern.
+     * Clamped to the [0, 1] range.
+     * Defaults to 1.
+     */
+    backgroundOpacityScalar?: number;
+    /**
+     * ELK layout direction.
+     * Defaults to 'RIGHT'.
+     */
+    layoutDirection?: FlowMapLayoutDirection;
+    /**
+     * Spacing between adjacent nodes within the same layer.
+     * Defaults to 80.
+     */
+    layoutNodeSpacing?: number;
+    /**
+     * Spacing between layers.
+     * Defaults to 100.
+     */
+    layoutLayerSpacing?: number;
+    /**
+     * Whether to fit the viewport to nodes on init / whenever the visible layout
+     * signature changes (node ids/positions). Defaults to true.
+     *
+     * Note: React Flow's own `fitView` prop is mount-only. FlowMap re-fits via an
+     * internal fitKey when this is enabled (both `"center"` and `"top"` aligns).
+     */
+    fitView?: boolean;
+    /**
+     * Options passed to React Flow `fitView` when `fitViewAlign` is `"center"`.
+     * When `padding` is omitted, `fitViewPadding` is used.
+     */
+    fitViewOptions?: FitViewOptions;
+    /**
+     * Viewport alignment used when fitting.
+     * `"center"` uses React Flow's default fitView.
+     * `"top"` keeps horizontal centering and pins the graph top to top padding.
+     * Defaults to `"center"`.
+     */
+    fitViewAlign?: FlowMapFitViewAlign;
+    /**
+     * fitView padding applied after automatic layout (and as the default
+     * `fitViewOptions.padding` when options omit padding).
+     * Defaults to 0.2.
+     */
+    fitViewPadding?: number;
+    /**
+     * Toggles automatic ELK layout application.
+     * Defaults to true.
+     */
+    enableAutoLayout?: boolean;
+    slots?: FlowMapSlots;
+    slotProps?: {
+        miniMap?: MiniMapProps;
+        controls?: ControlProps;
+    };
+}
+
+declare const FlowMap: react__default.FC<FlowMapProps>;
+
+interface FlowMapGroupRenderState {
+    collapsed: boolean;
+    collapsible: boolean;
+    descendantCount?: number;
+    onCollapseToggle?: () => void;
+}
+interface FlowMapCollapseState {
+    groupStates: Map<string, FlowMapGroupRenderState>;
+    groupToggleSlot?: FlowMapSlots['groupToggle'];
+    groupIds: string[];
+    collapsedGroups: Record<string, boolean>;
+    toggleGroupCollapse: (groupId: string) => void;
+    setCollapsedGroups: (collapsedGroups: Record<string, boolean>) => void;
+    setAllGroupsCollapsed: (collapsed: boolean) => void;
+}
+declare const FlowMapCollapseProvider: ({ value, children, }: {
+    value: FlowMapCollapseState;
+    children: React.ReactNode;
+}) => react_jsx_runtime.JSX.Element;
+declare const useFlowMapGroupState: (groupId: string, data: FlowMapGroupNodeData) => {
+    collapsed: boolean;
+    collapsible: boolean;
+    descendantCount: number | undefined;
+    onCollapseToggle: (() => void) | undefined;
+    groupToggleSlot: ((props: FlowMapGroupToggleSlotProps) => react.ReactNode) | undefined;
+};
+declare const useFlowMapCollapseControls: () => {
+    groupIds: string[];
+    collapsedGroups: Record<string, boolean>;
+    allGroupsCollapsed: boolean;
+    toggleGroupCollapse: (groupId: string) => void;
+    setCollapsedGroups: (collapsedGroups: Record<string, boolean>) => void;
+    setAllGroupsCollapsed: (collapsed: boolean) => void;
+};
+
+type FlowMapLayoutContextValue = {
+    layoutDirection: FlowMapLayoutDirection;
+    handles: FlowMapResolvedHandlePositions;
+    handlesSlot?: FlowMapSlots['handles'];
+};
+declare const FlowMapLayoutProvider: ({ layoutDirection, handlesSlot, children, }: {
+    layoutDirection: FlowMapLayoutDirection;
+    handlesSlot?: FlowMapSlots["handles"];
+    children: ReactNode;
+}) => react_jsx_runtime.JSX.Element;
+declare const useFlowMapLayout: () => FlowMapLayoutContextValue;
+declare const useFlowMapHandlePositions: () => FlowMapResolvedHandlePositions;
+
+declare const treeToNodesAndEdges: (root: FlowTreeNode) => {
+    nodes: FlowMapNode[];
+    edges: FlowMapEdge[];
+};
+
+type FlowMapHandleProps = Omit<HandleProps, 'position'> & {
+    side: FlowMapHandleSide;
+    /**
+     * Distance along the edge from the start of that side.
+     * Top/Bottom → `left`; Left/Right → `top`.
+     * Numbers are treated as px. Corners default to 32%/68% when omitted.
+     */
+    offset?: string | number;
+};
+declare const FlowMapHandle: ({ side, offset, style, ...rest }: FlowMapHandleProps) => react_jsx_runtime.JSX.Element;
+type FlowMapHandlePresetProps = Omit<FlowMapHandleProps, 'side'>;
+declare const TopHandle: (props: FlowMapHandlePresetProps) => react_jsx_runtime.JSX.Element;
+declare const RightHandle: (props: FlowMapHandlePresetProps) => react_jsx_runtime.JSX.Element;
+declare const BottomHandle: (props: FlowMapHandlePresetProps) => react_jsx_runtime.JSX.Element;
+declare const LeftHandle: (props: FlowMapHandlePresetProps) => react_jsx_runtime.JSX.Element;
+declare const TopLeftHandle: (props: FlowMapHandlePresetProps) => react_jsx_runtime.JSX.Element;
+declare const TopRightHandle: (props: FlowMapHandlePresetProps) => react_jsx_runtime.JSX.Element;
+declare const BottomLeftHandle: (props: FlowMapHandlePresetProps) => react_jsx_runtime.JSX.Element;
+declare const BottomRightHandle: (props: FlowMapHandlePresetProps) => react_jsx_runtime.JSX.Element;
+
+declare const _default$2: react__default.NamedExoticComponent<NodeProps>;
+
+declare const _default$1: react__default.NamedExoticComponent<NodeProps>;
+
+declare function CustomEdge({ source, target, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, style, markerEnd, sourceHandleId, targetHandleId, label, selected, }: EdgeProps): react_jsx_runtime.JSX.Element;
+declare const _default: react.MemoExoticComponent<typeof CustomEdge>;
+
+type FlowMapExportControlsProps = {
+    layoutDirection?: FlowMapLayoutDirection;
+    /** Filename for the PNG download. Default: flowmap.png */
+    downloadFileName?: string;
+};
+/**
+ * Extra ControlButtons for FlowMap: download a PNG snapshot of the viewport
+ * and copy a Mermaid flowchart of the visible graph.
+ */
+declare function FlowMapExportControls({ layoutDirection, downloadFileName, }: FlowMapExportControlsProps): react_jsx_runtime.JSX.Element;
+
+declare const nodeTypes: {
+    'custom-node': react.NamedExoticComponent<_xyflow_react.NodeProps>;
+    'group-node': react.NamedExoticComponent<_xyflow_react.NodeProps>;
+};
+declare const edgeTypes: {
+    'custom-edge': react.MemoExoticComponent<({ source, target, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, style, markerEnd, sourceHandleId, targetHandleId, label, selected, }: _xyflow_react.EdgeProps) => react_jsx_runtime.JSX.Element>;
+};
+
+/** Mermaid node ids must be alphanumeric / underscore. */
+declare const sanitizeMermaidId: (id: string) => string;
+declare const escapeMermaidLabel: (label: string) => string;
+/**
+ * Serialize visible FlowMap nodes/edges to a Mermaid flowchart string.
+ * Hidden nodes (and edges touching them) are omitted. Group nodes wrap
+ * their visible children in `subgraph` blocks when children exist.
+ */
+declare const flowMapToMermaid: (nodes: readonly FlowMapNode[], edges: readonly FlowMapEdge[], layoutDirection?: FlowMapLayoutDirection) => string;
+
+export { BottomHandle, BottomLeftHandle, BottomRightHandle, _default as CustomEdge, _default$2 as DefaultNode, FLOW_MAP_GROUP_NODE_TYPE, FlowMap, FlowMapCollapseProvider, type FlowMapCollapseState, type FlowMapEdge, FlowMapExportControls, type FlowMapExportControlsProps, type FlowMapFitViewAlign, type FlowMapGroupNodeData, type FlowMapGroupRenderState, type FlowMapGroupToggleSlotProps, FlowMapHandle, type FlowMapHandleAnchor, type FlowMapHandleProps, type FlowMapHandleSide, type FlowMapHandlesSlotProps, type FlowMapLayoutContextValue, type FlowMapLayoutDirection, FlowMapLayoutProvider, type FlowMapNode, type FlowMapNodeData, type FlowMapProps, type FlowMapResolvedHandlePositions, type FlowMapSlots, type FlowTreeGroup, type FlowTreeNode, _default$1 as GroupNode, HANDLER_IDs, HANDLE_POSITIONs, LeftHandle, RightHandle, TopHandle, TopLeftHandle, TopRightHandle, edgeTypes, escapeMermaidLabel, flowMapToMermaid, nodeTypes, resolveHandleAnchor, resolveHandlePositions, sanitizeMermaidId, treeToNodesAndEdges, useFlowMapCollapseControls, useFlowMapGroupState, useFlowMapHandlePositions, useFlowMapLayout };