panelui-web 0.0.0-stage → 0.2.0

package/dist/components/flow/flow-paths.js

@@ -0,0 +1,270 @@
+/**
+ * Edge geometry for Flow.
+ *
+ * Everything here is plain arithmetic on plain numbers: where on a node's face
+ * an edge attaches, which faces two nodes should use when nobody has said, and
+ * the path between two anchors in each of the four routings. It knows nothing
+ * about React or the page, which is what lets it be tested by itself.
+ *
+ * Kept out of `index.tsx` so the component file stays about components. Named
+ * `flow-paths` and not `paths`, because a copied component lands beside others
+ * and `paths.ts` would be a land grab on a very common name.
+ */
+/** The outward unit normal of a face — which way an edge sets off. */
+export function sideNormal(side) {
+    if (side === 'left')
+        return { x: -1, y: 0 };
+    if (side === 'right')
+        return { x: 1, y: 0 };
+    if (side === 'top')
+        return { x: 0, y: -1 };
+    return { x: 0, y: 1 };
+}
+/**
+ * Where on a face an edge attaches. `offset` runs 0–1 along the face, so two
+ * handles on the same side can sit apart without either knowing about the other.
+ */
+export function anchorOf(rect, side, offset) {
+    if (side === 'top') {
+        return { x: rect.x + rect.width * offset, y: rect.y };
+    }
+    if (side === 'bottom') {
+        return { x: rect.x + rect.width * offset, y: rect.y + rect.height };
+    }
+    if (side === 'left') {
+        return { x: rect.x, y: rect.y + rect.height * offset };
+    }
+    return { x: rect.x + rect.width, y: rect.y + rect.height * offset };
+}
+/**
+ * Pushes an anchor out along its own face's normal.
+ *
+ * For an end attached to something that draws its own border: landing exactly
+ * on the border puts the line under the stroke, where it reads as stopping
+ * short rather than as arriving.
+ */
+export function standOff(point, side, by) {
+    if (by === 0)
+        return point;
+    const normal = sideNormal(side);
+    return { x: point.x + normal.x * by, y: point.y + normal.y * by };
+}
+/**
+ * The faces two nodes should use when nobody has said. Whichever axis they are
+ * further apart on wins, so nodes side by side connect left-to-right and nodes
+ * stacked connect top-to-bottom — and the edge changes its mind as they are
+ * dragged past each other, which is what makes a hand-arranged graph stay
+ * readable without anyone re-specifying anything.
+ */
+export function autoSides(from, to) {
+    const dx = to.x + to.width / 2 - (from.x + from.width / 2);
+    const dy = to.y + to.height / 2 - (from.y + from.height / 2);
+    if (Math.abs(dx) > Math.abs(dy)) {
+        return dx >= 0 ? { from: 'right', to: 'left' } : { from: 'left', to: 'right' };
+    }
+    return dy >= 0 ? { from: 'bottom', to: 'top' } : { from: 'top', to: 'bottom' };
+}
+/** A line, for a graph where the routing is not the point. */
+export function straightPath(from, to) {
+    return `M${from.x},${from.y} L${to.x},${to.y}`;
+}
+/**
+ * How far a bezier's control point sits from its anchor.
+ *
+ * With room between the two faces it is half the gap, which gives the familiar
+ * S. When they overlap — the target is *behind* the source — the gap is
+ * negative and half of it would fold the curve inside out, so the offset grows
+ * with the square root of the overlap instead: enough to bulge the curve clear
+ * of the node, never enough to run away as the overlap grows.
+ */
+function controlOffset(distance, curvature) {
+    if (distance >= 0)
+        return 0.5 * distance;
+    return curvature * 25 * Math.sqrt(-distance);
+}
+function controlPoint(point, side, other, curvature) {
+    if (side === 'left') {
+        return { x: point.x - controlOffset(point.x - other.x, curvature), y: point.y };
+    }
+    if (side === 'right') {
+        return { x: point.x + controlOffset(other.x - point.x, curvature), y: point.y };
+    }
+    if (side === 'top') {
+        return { x: point.x, y: point.y - controlOffset(point.y - other.y, curvature) };
+    }
+    return { x: point.x, y: point.y + controlOffset(other.y - point.y, curvature) };
+}
+/** A cubic curve leaving and arriving perpendicular to each face. */
+export function bezierPath(from, fromSide, to, toSide, curvature) {
+    const c1 = controlPoint(from, fromSide, to, curvature);
+    const c2 = controlPoint(to, toSide, from, curvature);
+    return `M${from.x},${from.y} C${c1.x},${c1.y} ${c2.x},${c2.y} ${to.x},${to.y}`;
+}
+function distanceBetween(a, b) {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    return Math.sqrt(dx * dx + dy * dy);
+}
+/**
+ * One corner of a stepped path, rounded.
+ *
+ * The radius is capped at half of the shorter of the two segments meeting here,
+ * so a corner between two short runs tucks in rather than overshooting into the
+ * segment beyond it and drawing a path that doubles back.
+ */
+function bend(a, b, c, radius) {
+    const size = Math.min(distanceBetween(a, b) / 2, distanceBetween(b, c) / 2, radius);
+    // Three collinear points are not a corner.
+    if ((a.x === b.x && b.x === c.x) || (a.y === b.y && b.y === c.y)) {
+        return `L${b.x},${b.y}`;
+    }
+    if (a.y === b.y) {
+        const xDir = a.x < c.x ? -1 : 1;
+        const yDir = a.y < c.y ? 1 : -1;
+        return `L${b.x + size * xDir},${b.y}Q${b.x},${b.y} ${b.x},${b.y + size * yDir}`;
+    }
+    const xDir = a.x < c.x ? 1 : -1;
+    const yDir = a.y < c.y ? -1 : 1;
+    return `L${b.x},${b.y + size * yDir}Q${b.x},${b.y} ${b.x + size * xDir},${b.y}`;
+}
+/**
+ * An orthogonal route with rounded corners — the one that reads as wiring.
+ *
+ * Both ends first step `gap` points straight out along their own face, so the
+ * edge leaves the node square-on instead of grazing its corner. From there the
+ * two are joined by a single dog-leg, split across the axis they are further
+ * apart on.
+ *
+ * `radius` of 0 gives hard corners, which is the stepped variant.
+ */
+export function smoothStepPath(from, fromSide, to, toSide, radius, gap) {
+    const fromNormal = sideNormal(fromSide);
+    const toNormal = sideNormal(toSide);
+    let fromGap = {
+        x: from.x + fromNormal.x * gap,
+        y: from.y + fromNormal.y * gap,
+    };
+    let toGap = { x: to.x + toNormal.x * gap, y: to.y + toNormal.y * gap };
+    // The axis the two gap points are further apart on is the one the dog-leg
+    // travels along.
+    const horizontal = Math.abs(toGap.x - fromGap.x) > Math.abs(toGap.y - fromGap.y);
+    const facing = (fromNormal.x !== 0 && toNormal.x !== 0 && fromNormal.x !== toNormal.x) ||
+        (fromNormal.y !== 0 && toNormal.y !== 0 && fromNormal.y !== toNormal.y);
+    let middle;
+    if (facing) {
+        // Faces pointing at each other: meet in the middle of the run between them.
+        const midX = (fromGap.x + toGap.x) / 2;
+        const midY = (fromGap.y + toGap.y) / 2;
+        middle =
+            fromNormal.x !== 0
+                ? [
+                    { x: midX, y: fromGap.y },
+                    { x: midX, y: toGap.y },
+                ]
+                : [
+                    { x: fromGap.x, y: midY },
+                    { x: toGap.x, y: midY },
+                ];
+    }
+    else {
+        // Faces pointing the same way, or at right angles: one corner is enough.
+        // Which of the two possible corners depends on the travelling axis.
+        middle = horizontal ? [{ x: toGap.x, y: fromGap.y }] : [{ x: fromGap.x, y: toGap.y }];
+        // Two handles on the same face, closer together than the gap: the gap
+        // points sit between the anchors and the route folds back over itself.
+        // Push them out far enough to clear.
+        if (fromSide === toSide) {
+            const axis = fromNormal.x !== 0 ? 'x' : 'y';
+            const apart = Math.abs(from[axis] - to[axis]);
+            if (apart <= gap) {
+                const push = Math.min(gap - 1, gap - apart);
+                if (axis === 'x') {
+                    fromGap = { x: fromGap.x + fromNormal.x * push, y: fromGap.y };
+                    toGap = { x: toGap.x + toNormal.x * push, y: toGap.y };
+                    middle = [{ x: Math.max(fromGap.x, toGap.x), y: fromGap.y }];
+                }
+                else {
+                    fromGap = { x: fromGap.x, y: fromGap.y + fromNormal.y * push };
+                    toGap = { x: toGap.x, y: toGap.y + toNormal.y * push };
+                    middle = [{ x: fromGap.x, y: Math.max(fromGap.y, toGap.y) }];
+                }
+            }
+        }
+    }
+    const points = [from, fromGap, ...middle, toGap, to];
+    // Drop points that repeat the one before them — a duplicate reads as a
+    // zero-length segment and makes the bend either side of it collapse.
+    const route = [];
+    for (let i = 0; i < points.length; i += 1) {
+        const point = points[i];
+        const previous = route[route.length - 1];
+        if (previous && previous.x === point.x && previous.y === point.y)
+            continue;
+        route.push(point);
+    }
+    if (route.length < 2)
+        return `M${from.x},${from.y}`;
+    let d = `M${route[0].x},${route[0].y}`;
+    for (let i = 1; i < route.length - 1; i += 1) {
+        d +=
+            radius > 0
+                ? bend(route[i - 1], route[i], route[i + 1], radius)
+                : `L${route[i].x},${route[i].y}`;
+    }
+    const last = route[route.length - 1];
+    d += `L${last.x},${last.y}`;
+    return d;
+}
+/**
+ * The `d` string for an edge between two anchors, in whichever shape was asked
+ * for. One entry point, so an edge's path is a single call.
+ */
+export function edgePath(variant, from, fromSide, to, toSide, curvature, radius, gap) {
+    if (variant === 'straight')
+        return straightPath(from, to);
+    if (variant === 'bezier')
+        return bezierPath(from, fromSide, to, toSide, curvature);
+    return smoothStepPath(from, fromSide, to, toSide, variant === 'step' ? 0 : radius, gap);
+}
+/** Length of an edge's bounding diagonal — enough to size a dash cycle by. */
+export function edgeSpan(from, to) {
+    return distanceBetween(from, to);
+}
+/**
+ * The arrowhead at an edge's target, as its own closed path.
+ *
+ * SVG has `marker-end` for exactly this, and it is the obvious way to do it.
+ * It is not used, because a path carrying a marker reference stops picking up
+ * new geometry on re-render — the arrow-bearing edges freeze where they were
+ * first drawn while arrow-less ones follow their nodes. Drawing the triangle
+ * as an ordinary path costs nine numbers and behaves.
+ *
+ * `dirX`/`dirY` is the unit direction of travel *into* the target.
+ */
+export function arrowHeadPath(tip, dirX, dirY, size) {
+    const length = Math.sqrt(dirX * dirX + dirY * dirY) || 1;
+    const ux = dirX / length;
+    const uy = dirY / length;
+    // The perpendicular, for the two back corners.
+    const px = -uy;
+    const py = ux;
+    const baseX = tip.x - ux * size;
+    const baseY = tip.y - uy * size;
+    const half = size * 0.45;
+    return (`M${tip.x},${tip.y} ` +
+        `L${baseX + px * half},${baseY + py * half} ` +
+        `L${baseX - px * half},${baseY - py * half} Z`);
+}
+/**
+ * Which way an edge is travelling as it arrives. Every routing but `straight`
+ * comes in perpendicular to the target's face, so the face decides it; a
+ * straight line comes in along itself.
+ */
+export function arrivalDirection(variant, from, to, toSide) {
+    if (variant === 'straight') {
+        return { x: to.x - from.x, y: to.y - from.y };
+    }
+    const normal = sideNormal(toSide);
+    // The face points outward; the edge arrives against it.
+    return { x: -normal.x, y: -normal.y };
+}

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 };