panelui-web 0.0.0-stage → 0.1.0

package/dist/components/flow/index.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Flow — a canvas of nodes joined by edges, that you pan, zoom and rearrange.
+ *
+ * ```tsx
+ * <Flow>
+ *   <Flow.Background variant="dots" />
+ *   <Flow.Node id="source" position={{ x: 24, y: 40 }}>…</Flow.Node>
+ *   <Flow.Node id="build" position={{ x: 24, y: 200 }}>…</Flow.Node>
+ *   <Flow.Edge from="source" to="build" dashed animated arrow />
+ *   <Flow.Controls />
+ * </Flow>
+ * ```
+ *
+ * ## The same parts as the app
+ *
+ * The parts and their props are the app library's Flow, so a graph written
+ * for one reads the same in the other. What differs is the hand: here the
+ * pane is dragged with a mouse, zoomed with a pinch or with Control and the
+ * wheel, and every node can be reached and moved from the keyboard.
+ *
+ * ## Where the positions live
+ *
+ * A node's `position` is where it starts. From then on the canvas holds it:
+ * a drag moves it there, and `onNodeDragEnd` says where it came to rest. Pass
+ * a new `position` and the node goes to it, which is how nodes are driven
+ * from outside.
+ *
+ * Edges are drawn from the boxes of the nodes they join, measured off the
+ * page. An edge therefore follows a node whatever is inside it, and redraws
+ * as either end is dragged.
+ *
+ * ## Three gestures, one canvas
+ *
+ * The pane pans, a node drags, and a handle draws a new connection. Each is
+ * taken by the innermost thing under the pointer, which is what a hand
+ * expects.
+ */
+import { type ComponentProps, type ReactNode } from 'react';
+import { type FlowPoint, type FlowRect, type FlowSide } from './flow-paths.js';
+export type FlowEdgeVariant = 'bezier' | 'smoothstep' | 'step' | 'straight';
+/** Which of the theme's roles an edge is drawn in. */
+export type FlowColor = 'primary' | 'info' | 'success' | 'warning' | 'destructive';
+/** Where the canvas is looking: how far it is panned, and how far zoomed. */
+export interface FlowViewport {
+    x: number;
+    y: number;
+    zoom: number;
+}
+export interface FlowNodePosition {
+    x: number;
+    y: number;
+}
+/** One end of an edge: a node, and optionally one of its handles by `id`. */
+export interface FlowEndpoint {
+    node: string;
+    handle?: string;
+}
+export type FlowEndpointReference = string | FlowEndpoint;
+/** What `onConnect` is handed when a connection lands. */
+export interface FlowConnection {
+    /** Node the drag started from. */
+    source: string;
+    /** Handle it started from, when that handle has an `id`. */
+    sourceHandle?: string;
+    /** Node it was dropped on. */
+    target: string;
+    /** Handle it was dropped on, when it landed on one with an `id`. */
+    targetHandle?: string;
+}
+export interface FlowProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /** Where the canvas looks to begin with. */
+    defaultViewport?: FlowViewport;
+    /** The furthest out it can be zoomed. */
+    minZoom?: number;
+    /** The furthest in it can be zoomed. */
+    maxZoom?: number;
+    /** Whether dragging the pane pans it. */
+    panOnDrag?: boolean;
+    /** Whether a pinch, or Control with the wheel, zooms it. */
+    zoomOnPinch?: boolean;
+    /** Fits every node into view once they have been measured. */
+    fitViewOnMount?: boolean;
+    /** The room left round the nodes when fitting them, in pixels. */
+    fitViewPadding?: number;
+    /** Called as the canvas is panned or zoomed. */
+    onViewportChange?: (viewport: FlowViewport) => void;
+    /** Called with a node's new position when a drag or a key press has moved it. */
+    onNodeDragEnd?: (id: string, position: FlowNodePosition) => void;
+    /** Called when a connection drawn from a handle lands on another node. */
+    onConnect?: (connection: FlowConnection) => void;
+    /** Decides whether a connection may land. Without it, any two different nodes may be joined. */
+    isValidConnection?: (connection: FlowConnection) => boolean;
+    /** What a screen reader calls the canvas. */
+    label?: string;
+    children?: ReactNode;
+}
+declare function FlowRoot({ defaultViewport, minZoom, maxZoom, panOnDrag, zoomOnPinch, fitViewOnMount, fitViewPadding, onViewportChange, onNodeDragEnd, onConnect, isValidConnection, label, className, children, onKeyDown, ...props }: FlowProps): import("react").JSX.Element;
+declare namespace FlowRoot {
+    var displayName: string;
+}
+export interface FlowBackgroundProps {
+    /** Dots, a grid of lines, small crosses, or nothing. */
+    variant?: 'dots' | 'lines' | 'cross' | 'none';
+    /** The distance from one mark to the next, in pixels at a zoom of 1. */
+    gap?: number;
+    /** How big a mark is: a dot's radius, a line's thickness, half a cross's arm. */
+    size?: number;
+    className?: string;
+}
+/** The pattern behind the graph, which moves and scales with it. */
+declare function FlowBackground({ variant, gap, size, className }: FlowBackgroundProps): import("react").ReactPortal | null;
+declare namespace FlowBackground {
+    var displayName: string;
+}
+export interface FlowNodeProps extends Omit<ComponentProps<'div'>, 'id'> {
+    /** What edges and `onNodeDragEnd` call this node. */
+    id: string;
+    /** Where its top left corner is, on the graph. */
+    position: FlowNodePosition;
+    /** Whether it can be dragged and moved with the arrow keys. */
+    draggable?: boolean;
+    /** Draws it as the one that has been picked. */
+    selected?: boolean;
+    /** Called when it is pressed without being dragged, or with Enter. */
+    onPress?: () => void;
+    /** Called when Delete or Backspace is pressed on it. */
+    onDelete?: () => void;
+    /** How far one arrow key press moves it, in pixels. Shift moves four times as far. */
+    moveStep?: number;
+}
+/** A box on the graph. Whatever is inside it is yours. */
+declare function FlowNode({ id, position, draggable, selected, onPress, onDelete, moveStep, className, style, children, ...props }: FlowNodeProps): import("react").JSX.Element;
+declare namespace FlowNode {
+    var displayName: string;
+}
+export interface FlowGroupProps extends FlowNodeProps {
+    /** Written in the corner of the group. */
+    label?: ReactNode;
+}
+/**
+ * A dashed box round a few things that belong together. It is a node like any
+ * other: it is dragged as one, and an edge can be joined to it.
+ */
+declare function FlowGroup({ id, position, draggable, selected: _selected, onPress, onDelete, moveStep, label, className, style, children, ...props }: FlowGroupProps): import("react").JSX.Element;
+declare namespace FlowGroup {
+    var displayName: string;
+}
+export interface FlowHandleProps extends Omit<ComponentProps<'span'>, 'id'> {
+    /** A name for this handle, so an edge can be joined to it and not only to the node. */
+    id?: string;
+    /** Which face of the node it sits on. */
+    position?: FlowSide;
+    /** How far along that face, from 0 to 1. */
+    offset?: number;
+}
+/** A point on a node's edge that a connection can be drawn from, or dropped on. */
+declare function FlowHandle({ id, position, offset, className, style, ...props }: FlowHandleProps): import("react").JSX.Element;
+declare namespace FlowHandle {
+    var displayName: string;
+}
+export interface FlowEdgeProps {
+    /** Where it leaves from: a node's `id`, or `{ node, handle }`. */
+    from: FlowEndpointReference;
+    /** Where it arrives. */
+    to: FlowEndpointReference;
+    /** A curve, a rounded right-angled route, a square one, or a straight line. */
+    variant?: FlowEdgeVariant;
+    /** Sets the dashes marching towards the target. */
+    animated?: boolean;
+    /** Draws it dashed. */
+    dashed?: boolean;
+    /** One of the theme's roles. Without it the edge is a quiet grey. */
+    color?: FlowColor;
+    /** How thick the line is, in pixels at a zoom of 1. */
+    width?: number;
+    /** Draws an arrowhead where it arrives. */
+    arrow?: boolean;
+    /** The face it leaves from. Worked out from where the two nodes are when left out. */
+    fromSide?: FlowSide;
+    /** The face it arrives at. */
+    toSide?: FlowSide;
+    /** How round the corners of a `smoothstep` route are. */
+    radius?: number;
+    /** How far a routed edge runs straight out of a node before it turns. */
+    gap?: number;
+    /** How far a `bezier` bulges when its target is behind its source. */
+    curvature?: number;
+}
+/** A line from one node to another, which follows them as they move. */
+declare function FlowEdge({ from, to, variant, animated, dashed, color, width, arrow, fromSide, toSide, radius, gap, curvature, }: FlowEdgeProps): import("react").JSX.Element | null;
+declare namespace FlowEdge {
+    var displayName: string;
+}
+type FlowCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export interface FlowControlsProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /** Shows the two zoom buttons. */
+    zoom?: boolean;
+    /** Shows the button that fits every node into view. */
+    fit?: boolean;
+    /** Shows the button that locks the canvas against panning, zooming and dragging. */
+    lock?: boolean;
+    /** How much one press of a zoom button zooms. */
+    step?: number;
+    /** Which corner of the canvas they sit in. */
+    position?: FlowCorner;
+}
+/** Buttons for what a pinch and a drag do, for anyone without either. */
+declare function FlowControls({ zoom, fit, lock, step, position, className, ...props }: FlowControlsProps): import("react").ReactPortal | null;
+declare namespace FlowControls {
+    var displayName: string;
+}
+export interface FlowMiniMapProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /** How wide the map is, in pixels. */
+    width?: number;
+    /** How tall the map is, in pixels. */
+    height?: number;
+    /** Which corner of the canvas it sits in. */
+    position?: FlowCorner;
+}
+/** The whole graph, small, with the part in view marked on it. */
+declare function FlowMiniMap({ width, height, position, className, style, ...props }: FlowMiniMapProps): import("react").ReactPortal | null;
+declare namespace FlowMiniMap {
+    var displayName: string;
+}
+export declare const Flow: typeof FlowRoot & {
+    Background: typeof FlowBackground;
+    Node: typeof FlowNode;
+    Handle: typeof FlowHandle;
+    Edge: typeof FlowEdge;
+    Group: typeof FlowGroup;
+    Controls: typeof FlowControls;
+    MiniMap: typeof FlowMiniMap;
+};
+export { FlowBackground, FlowNode, FlowHandle, FlowEdge, FlowGroup, FlowControls, FlowMiniMap };
+export type { FlowSide, FlowRect, FlowPoint };