@statelyai/flow-react 0.4.0

package/dist/esm/index.d.ts

@@ -0,0 +1,306 @@
+import * as react10 from "react";
+import { CSSProperties, HTMLAttributes, ReactNode, RefObject } from "react";
+import { AnchorSpec, ConnectionEndedEvent, CreateFlowOptions, EdgePathData, FlowColorMode, FlowController, FlowEdge, FlowGraph, FlowInputMode, FlowNode, FlowProfile, FlowStoreContext, LayoutRequestedEvent, Point, Rect, Viewport, VisualPort } from "@statelyai/flow";
+import { ResolvedFlowColorMode } from "@statelyai/flow-dom";
+
+//#region src/createFlowInstance.d.ts
+type FlowSelector<T> = (context: FlowStoreContext) => T;
+type FlowSelectorEquality<T> = (current: T, next: T) => boolean;
+type FlowStoreListener<T = unknown> = {
+  selector: FlowSelector<T>;
+  onChange: (value: T, previousValue: T, context: FlowStoreContext) => void;
+  isEqual?: FlowSelectorEquality<T>;
+  fireImmediately?: boolean;
+};
+type FlowEventListeners = {
+  connectionEnded?: (event: ConnectionEndedEvent) => void;
+  layoutRequested?: (event: LayoutRequestedEvent) => void;
+};
+type FlowInstanceSettings = Omit<CreateFlowOptions, "graph">;
+type CreateFlowInstanceOptions = {
+  graph: FlowGraph;
+  settings?: FlowInstanceSettings;
+  listeners?: FlowStoreListener[];
+  events?: FlowEventListeners;
+};
+type FlowInstance = FlowController & {
+  getSnapshot(): FlowStoreContext;
+  /**
+   * Convert window client coordinates (e.g. `event.clientX/Y` from drops or
+   * window-level listeners) to canvas coordinates, accounting for the
+   * attached container's position. Unlike `screenToCanvas`, which expects
+   * container-relative pixels.
+   */
+  clientToCanvas(point: Point): Point;
+  listen<T>(selector: FlowSelector<T>, listener: FlowStoreListener<T>["onChange"], options?: {
+    isEqual?: FlowSelectorEquality<T>;
+    fireImmediately?: boolean;
+  }): () => void;
+};
+declare function createFlowInstance(options: CreateFlowInstanceOptions): FlowInstance;
+//#endregion
+//#region src/FlowInstanceContext.d.ts
+declare function FlowInstanceProvider(props: {
+  flow: FlowInstance;
+  children: ReactNode;
+}): react10.JSX.Element;
+declare function useFlowInstance(): FlowInstance;
+declare function useOptionalFlowInstance(): FlowInstance | null;
+//#endregion
+//#region src/hooks.d.ts
+type UseCreateFlowInstanceOptions = CreateFlowInstanceOptions;
+type UseFlowOptions = UseCreateFlowInstanceOptions;
+declare function useFlow(options: UseFlowOptions): FlowInstance;
+declare function useCreateFlowInstance(options: UseCreateFlowInstanceOptions): FlowInstance;
+declare function useFlowSelector<T>(selector: FlowSelector<T>, options?: {
+  flow?: FlowInstance;
+  isEqual?: FlowSelectorEquality<T>;
+}): T;
+declare function useFlowContext(): FlowStoreContext;
+/**
+ * Like `useFlowSelector`, but subscribed through the entity-change notifier:
+ * the selector re-runs only when the entity with `id` may have changed, not
+ * on every store transition. This is what makes thousands of mounted entity
+ * views affordable — see BENCHMARK.md.
+ */
+declare function useFlowEntity<T>(id: string, selector: FlowSelector<T>, options?: {
+  flow?: FlowInstance;
+  isEqual?: FlowSelectorEquality<T>;
+}): T;
+declare function useFlowValue<T>(selector: FlowSelector<T>, isEqual?: FlowSelectorEquality<T>): T;
+type DerivedEntityFields = {
+  selected: boolean;
+  focused: boolean;
+  hovered: boolean;
+  props: HTMLAttributes<HTMLElement> & Record<`data-${string}`, string>;
+};
+type FlowNodeBinding<TData = any> = FlowNode<TData> & DerivedEntityFields;
+type FlowEdgeBinding<TEdgeData = any, TLabelData = any> = FlowEdge<TEdgeData, TLabelData> & DerivedEntityFields & {
+  pathData: ReturnType<FlowInstance['getAllEdgePaths']> extends Map<string, infer TPath> ? TPath | null : never;
+};
+type FlowPortBinding = VisualPort & DerivedEntityFields & {
+  id: string;
+  nodeId: string;
+  portName: string;
+};
+type EntitySelector<TValue, TSelected> = (value: TValue, context: FlowStoreContext) => TSelected;
+declare function useFlowNode<TData = any>(id: string): FlowNodeBinding<TData>;
+declare function useFlowNode<TData = any, TSelected = unknown>(id: string, selector: EntitySelector<FlowNode<TData>, TSelected>, isEqual?: FlowSelectorEquality<TSelected>): TSelected;
+declare function useFlowEdge<TEdgeData = any, TLabelData = any>(id: string): FlowEdgeBinding<TEdgeData, TLabelData>;
+declare function useFlowEdge<TEdgeData = any, TLabelData = any, TSelected = unknown>(id: string, selector: EntitySelector<FlowEdge<TEdgeData, TLabelData>, TSelected>, isEqual?: FlowSelectorEquality<TSelected>): TSelected;
+declare function useFlowPort(id: string): FlowPortBinding;
+declare function useFlowPort<TSelected>(id: string, selector: EntitySelector<FlowPortBinding, TSelected>, isEqual?: FlowSelectorEquality<TSelected>): TSelected;
+declare function useFlowViewport(): Viewport;
+declare function useFlowMeasurement(id: string): Rect | null;
+//#endregion
+//#region src/useFlowInput.d.ts
+type UseFlowInputOptions = {
+  /**
+   * Input modes, or a resolver from store context. Defaults to the store
+   * profile's input modes (when a profile is given) and otherwise to the
+   * core default set, which follows the store's `context.mode`
+   * (interactive / readonly). Initial-only: changes after mount are ignored —
+   * swap behavior at runtime via `flow.trigger.setMode(...)` or a
+   * context-aware resolver.
+   */
+  modes?: FlowInputMode[] | ((context: FlowStoreContext) => FlowInputMode[]);
+  /** Store profile whose per-mode `input.modes` drive the runtime. */
+  profile?: FlowProfile;
+};
+/**
+ * Bind a container element to the core input runtime: all pointer, wheel,
+ * and keyboard gestures inside the container are recognized by input modes
+ * and applied to the flow store. This replaces hand-written gesture handlers.
+ */
+declare function useFlowInput(flow: FlowInstance, containerRef: RefObject<HTMLElement | null>, options?: UseFlowInputOptions): void;
+//#endregion
+//#region src/StatelyFlow.d.ts
+type RenderNodeProps<TNodeData = unknown> = {
+  flow: FlowInstance;
+  node: FlowNode<TNodeData>;
+  bounds: Rect;
+  selected: boolean;
+  dragging: boolean;
+  hovered: boolean;
+  highlights: ReadonlyArray<{
+    kind: string;
+    meta: unknown;
+  }>;
+};
+type RenderEdgeProps<TEdgeData = unknown> = {
+  flow: FlowInstance;
+  edge: FlowEdge<TEdgeData>;
+  pathData: EdgePathData;
+  selected: boolean;
+  hovered: boolean;
+  highlights: ReadonlyArray<{
+    kind: string;
+    meta: unknown;
+  }>;
+};
+type StatelyFlowProps<TNodeData = unknown, TEdgeData = unknown> = {
+  flow?: FlowInstance;
+  graph: FlowGraph<TNodeData, TEdgeData>;
+  settings?: FlowInstanceSettings;
+  listeners?: FlowStoreListener[];
+  events?: FlowEventListeners;
+  renderNode?: (props: RenderNodeProps<TNodeData>) => ReactNode;
+  renderEdge?: (props: RenderEdgeProps<TEdgeData>) => ReactNode;
+  /**
+   * Only mount nodes/edges that intersect the viewport (plus an overscan
+   * margin). Recommended for large graphs.
+   */
+  onlyRenderVisible?: boolean;
+  /**
+   * Override the input modes driving gestures (initial-only). Defaults to
+   * the store profile's input modes when `settings.store.profile` is set,
+   * otherwise to the core defaults. Example — custom connection validity:
+   *
+   * ```tsx
+   * inputModes={[
+   *   ...defaultInputModes.filter((mode) => mode.id !== "connect"),
+   *   connectMode({ isValid: myValidity }),
+   * ]}
+   * ```
+   */
+  inputModes?: FlowInputMode[] | ((context: FlowStoreContext) => FlowInputMode[]);
+  className?: string;
+  style?: CSSProperties;
+  background?: ReactNode;
+  children?: ReactNode;
+};
+declare function StatelyFlow<TNodeData = unknown, TEdgeData = unknown>(props: StatelyFlowProps<TNodeData, TEdgeData>): react10.JSX.Element;
+//#endregion
+//#region src/FlowToolbar.d.ts
+/** Border-box size of an element, kept current via ResizeObserver. */
+declare function useMeasuredSize<T extends HTMLElement>(deps?: ReadonlyArray<unknown>): readonly [(node: T | null) => void, {
+  width: number;
+  height: number;
+}];
+type UseFlowToolbarOptions = {
+  /**
+   * Which entities to anchor to. Defaults to the current selection — so one
+   * toolbar implementation covers nodes, edges, and multi-selections.
+   */
+  ids?: string[];
+  /** Gap between the anchor and the toolbar (default 10). */
+  offset?: number;
+  /** Minimum gap from the container edges (default 8). */
+  padding?: number;
+};
+type FlowToolbarState = {
+  /** Attach to the toolbar element (measures it). */
+  setRef: (node: HTMLDivElement | null) => void;
+  /** Positioning style for the toolbar element. */
+  style: CSSProperties;
+  /** False when nothing is anchored (render nothing). */
+  visible: boolean;
+  /** The resolved screen-space anchor, when visible. */
+  anchor: Rect | null;
+  /** Which side of the anchor the toolbar sits on. */
+  side: "top" | "bottom";
+};
+declare function useFlowToolbar(options?: UseFlowToolbarOptions): FlowToolbarState;
+type FlowToolbarProps = UseFlowToolbarOptions & {
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+};
+/**
+ * Unstyled positioned toolbar anchored to the selection (or explicit `ids`).
+ * Marked `data-flow-interactive`, so its contents receive pointer events
+ * unopposed by canvas gestures.
+ */
+declare function FlowToolbar(props: FlowToolbarProps): react10.JSX.Element | null;
+//#endregion
+//#region src/MiniMap.d.ts
+type MiniMapProps = {
+  width?: number;
+  height?: number;
+  /** Padding around content as a fraction of its size (default 0.1). */
+  padding?: number;
+  className?: string;
+  style?: CSSProperties;
+  /** Render one node marker; defaults to a plain `<rect>`. */
+  renderNode?: (node: FlowNode, rect: Rect) => ReactNode;
+};
+/**
+ * Overview map. Deliberately thin: all math lives in core
+ * (`getMinimapProjection`, `viewportCenteredOn`) and every interaction is a
+ * plain store trigger — this component is exactly what you would write in
+ * userland, kept here as a convenience.
+ */
+declare function MiniMap(props: MiniMapProps): react10.JSX.Element;
+//#endregion
+//#region src/Controls.d.ts
+type ControlsProps = {
+  className?: string;
+  style?: CSSProperties;
+  /** Extra buttons appended after the built-ins. */
+  children?: ReactNode;
+};
+/**
+ * Zoom/fit toolbar. Deliberately thin: every button is one store trigger
+ * (`zoomBy`, `fitView`) — replicate or extend it freely in userland.
+ */
+declare function Controls(props: ControlsProps): react10.JSX.Element;
+//#endregion
+//#region src/EntityAnchor.d.ts
+type EntityAnchorProps = {
+  bounds: Rect;
+  anchor: AnchorSpec;
+  inverseScale?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  children: ReactNode;
+};
+declare function EntityAnchor(props: EntityAnchorProps): react10.JSX.Element;
+//#endregion
+//#region src/Port.d.ts
+type PortProps = {
+  name: string;
+  /**
+   * Whether the DOM element reports its bounds back to the graph (default
+   * true). Ports are unidirectional, one way or the other:
+   *
+   * - DOM-owned (default): position the element with your own CSS (offsets,
+   *   percentages, flex…) — NEVER from `port.x`/`port.y` — and the graph's
+   *   port geometry follows the DOM.
+   * - Graph-owned (`measured={false}`): position the element FROM
+   *   `port.x`/`port.y` (layout results, "virtual" ports) and nothing is
+   *   written back.
+   *
+   * Mixing the two (positioning from `port.x` while measuring) creates a
+   * feedback loop and runs away.
+   */
+  measured?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  children?: ReactNode;
+};
+/**
+ * A connection port. Purely declarative: it renders the
+ * `data-flow-port-name`/`data-flow-node-id` attributes that the input
+ * runtime's `connectMode` recognizes, and reports its measured bounds to the
+ * store. The connection gesture itself (start/move/validate/end) lives in
+ * core — customize it by swapping `connectMode({ isValid })` in the
+ * `inputModes` prop of `StatelyFlow` (or your own `useFlowInput` call), and
+ * observe results via `flow.on("connectionEnded", …)` or the store's
+ * `connection` state.
+ */
+declare function Port(props: PortProps): react10.JSX.Element;
+//#endregion
+//#region src/ColorMode.d.ts
+type FlowColorModeScopeProps = {
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+};
+declare function FlowColorModeScope(props: FlowColorModeScopeProps): react10.JSX.Element;
+declare function useFlowColorMode(): {
+  colorMode: FlowColorMode;
+  resolvedColorMode: ResolvedFlowColorMode;
+};
+declare function useApplyFlowColorMode(element: HTMLElement | null): void;
+//#endregion
+export { Controls, type ControlsProps, type CreateFlowInstanceOptions, EntityAnchor, type EntityAnchorProps, FlowColorModeScope, type FlowColorModeScopeProps, type FlowEdgeBinding, type FlowEventListeners, type FlowInstance, FlowInstanceProvider, type FlowInstanceSettings, type FlowNodeBinding, type FlowPortBinding, type FlowSelector, type FlowSelectorEquality, type FlowStoreListener, FlowToolbar, type FlowToolbarProps, type FlowToolbarState, MiniMap, type MiniMapProps, Port, type PortProps, type RenderEdgeProps, type RenderNodeProps, StatelyFlow, type StatelyFlowProps, type UseCreateFlowInstanceOptions, type UseFlowInputOptions, type UseFlowOptions, type UseFlowToolbarOptions, createFlowInstance, useApplyFlowColorMode, useCreateFlowInstance, useFlow, useFlowColorMode, useFlowContext, useFlowEdge, useFlowEntity, useFlowInput, useFlowInstance, useFlowMeasurement, useFlowNode, useFlowPort, useFlowSelector, useFlowToolbar, useFlowValue, useFlowViewport, useMeasuredSize, useOptionalFlowInstance };