chore(types): add tsdocs

packages/system/src/types/edges.ts

@@ -103,6 +103,12 @@ export type EdgeMarker = {
 
 export type EdgeMarkerType = string | EdgeMarker;
 
+/**
+ * Edges may optionally have a marker on either end. The MarkerType type enumerates
+ * the options available to you when configuring a given marker.
+ *
+ * @public
+ */
 export enum MarkerType {
   Arrow = 'arrow',
   ArrowClosed = 'arrowclosed',

packages/system/src/types/general.ts

@@ -28,8 +28,8 @@ export type FitBounds = (bounds: Rect, options?: FitBoundsOptions) => Promise<bo
 
 /**
  * The `Connection` type is the basic minimal description of an [`Edge`](/api-reference/types/edge)
- *between two nodes. The [`addEdge`](/api-reference/utils/add-edge) util can be used to upgrade
- *a `Connection` to an [`Edge`](/api-reference/types/edge).
+ * between two nodes. The [`addEdge`](/api-reference/utils/add-edge) util can be used to upgrade
+ * a `Connection` to an [`Edge`](/api-reference/types/edge).
  *
  * @public
  */
@@ -40,15 +40,28 @@ export type Connection = {
   targetHandle: string | null;
 };
 
-// TODO: remove in next version
+/**
+ * The `HandleConnection` type is an extention of a basic [Connection](/api-reference/types/connection) that includes the `edgeId`.
+ */
 export type HandleConnection = Connection & {
   edgeId: string;
 };
 
+/**
+ * The `NodeConnection` type is an extention of a basic [Connection](/api-reference/types/connection) that includes the `edgeId`.
+ *
+ */
 export type NodeConnection = Connection & {
   edgeId: string;
 };
 
+/**
+ * The `ConnectionMode` is used to set the mode of connection between nodes.
+ * The `Strict` mode is the default one and only allows source to target edges.
+ * `Loose` mode allows source to source and target to target edges as well.
+ *
+ * @public
+ */
 export enum ConnectionMode {
   Strict = 'strict',
   Loose = 'loose',
@@ -66,6 +79,9 @@ export type OnConnectEnd = (event: MouseEvent | TouchEvent, connectionState: Fin
 
 export type IsValidConnection = (edge: EdgeBase | Connection) => boolean;
 
+/**
+ * @inline
+ */
 export type FitViewParamsBase<NodeType extends NodeBase> = {
   nodes: Map<string, InternalNodeBase<NodeType>>;
   width: number;
@@ -75,6 +91,9 @@ export type FitViewParamsBase<NodeType extends NodeBase> = {
   maxZoom: number;
 };
 
+/**
+ * @inline
+ */
 export type FitViewOptionsBase<NodeType extends NodeBase = NodeBase> = {
   padding?: number;
   includeHiddenNodes?: boolean;
@@ -84,6 +103,17 @@ export type FitViewOptionsBase<NodeType extends NodeBase = NodeBase> = {
   nodes?: (NodeType | { id: string })[];
 };
 
+/**
+ * Internally, React Flow maintains a coordinate system that is independent of the
+ * rest of the page. The `Viewport` type tells you where in that system your flow
+ * is currently being display at and how zoomed in or out it is.
+ *
+ * @public
+ * @remarks A `Transform` has the same properties as the viewport, but they represent
+ * different things. Make sure you don't get them muddled up or things will start
+ * to look weird!
+ *
+ */
 export type Viewport = {
   x: number;
   y: number;
@@ -94,12 +124,23 @@ export type KeyCode = string | Array<string>;
 
 export type SnapGrid = [number, number];
 
+/**
+ * This enum is used to set the different modes of panning the viewport when the
+ * user scrolls. The `Free` mode allows the user to pan in any direction by scrolling
+ * with a device like a trackpad. The `Vertical` and `Horizontal` modes restrict
+ * scroll panning to only the vertical or horizontal axis, respectively.
+ *
+ * @public
+ */
 export enum PanOnScrollMode {
   Free = 'free',
   Vertical = 'vertical',
   Horizontal = 'horizontal',
 }
 
+/**
+ * @inline
+ */
 export type ViewportHelperFunctionOptions = {
   duration?: number;
 };
@@ -120,6 +161,14 @@ export type D3ZoomHandler = (this: Element, event: any, d: unknown) => void;
 
 export type UpdateNodeInternals = (nodeId: string | string[]) => void;
 
+/**
+ * This type is mostly used to help position things on top of the flow viewport. For
+ * example both the [`<MiniMap />`](/api-reference/components/minimap) and
+ * [`<Controls />`](/api-reference/components/controls) components take a `position`
+ * prop of this type.
+ *
+ * @public
+ */
 export type PanelPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 
 export type ProOptions = {
@@ -183,7 +232,8 @@ export type ConnectionInProgress<NodeType extends InternalNodeBase = InternalNod
 };
 
 /**
- * The `ConnectionState` type bundles all information about an ongoing connection. It is returned by the [`useConnection`](/api-reference/hooks/use-connection) hook.
+ * The `ConnectionState` type bundles all information about an ongoing connection.
+ * It is returned by the [`useConnection`](/api-reference/hooks/use-connection) hook.
  *
  * @public
  */

packages/system/src/types/nodes.ts

@@ -4,6 +4,7 @@ import { Optional } from '../utils/types';
 /**
  * Framework independent node data structure.
  *
+ * @inline
  * @typeParam NodeData - type of the node data
  * @typeParam NodeType - type of the node
  */
@@ -80,7 +81,7 @@ export type InternalNodeBase<NodeType extends NodeBase = NodeBase> = NodeType &
     z: number;
     /**
      * Holds a reference to the original node object provided by the user.
-     * Used as an optimization to avoid certain operations. 
+     * Used as an optimization to avoid certain operations.
      */
     userNode: NodeType;
     handleBounds?: NodeHandleBounds;
@@ -89,7 +90,7 @@ export type InternalNodeBase<NodeType extends NodeBase = NodeBase> = NodeType &
 };
 
 /**
- * The node data structure that gets used for the nodes prop.
+ * The node data structure that gets used for the custom nodes props.
  *
  * @public
  */
@@ -141,10 +142,22 @@ export type NodeDragItem = {
   expandParent?: boolean;
 };
 
+/**
+ * The origin of a Node determines how it is placed relative to its own coordinates.
+ * `[0, 0]` places it at the top left corner, `[0.5, 0.5]` right in the center and
+ * `[1, 1]` at the bottom right of its position.
+ *
+ * @public
+ */
 export type NodeOrigin = [number, number];
 
 export type OnSelectionDrag = (event: MouseEvent, nodes: NodeBase[]) => void;
 
+/**
+ * Type for the handles of a node
+ *
+ * @public
+ */
 export type NodeHandle = Omit<Optional<Handle, 'width' | 'height'>, 'nodeId'>;
 
 export type Align = 'center' | 'start' | 'end';

packages/system/src/types/utils.ts

@@ -1,3 +1,10 @@
+/**
+ * While [`PanelPosition`](/api-reference/types/panel-position) can be used to place a
+ * component in the corners of a container, the `Position` enum is less precise and used
+ * primarily in relation to edges and handles.
+ *
+ * @public
+ */
 export enum Position {
   Left = 'left',
   Top = 'top',
@@ -12,6 +19,11 @@ export const oppositePosition = {
   [Position.Bottom]: Position.Top,
 };
 
+/**
+ * All positions are stored in an object with x and y coordinates.
+ *
+ * @public
+ */
 export type XYPosition = {
   x: number;
   y: number;
@@ -35,12 +47,12 @@ export type Transform = [number, number, number];
 
 /**
  * A coordinate extent represents two points in a coordinate system: one in the top
- *left corner and one in the bottom right corner. It is used to represent the
- *bounds of nodes in the flow or the bounds of the viewport.
+ * left corner and one in the bottom right corner. It is used to represent the
+ * bounds of nodes in the flow or the bounds of the viewport.
  *
  * @public
  *
  * @remarks Props that expect a `CoordinateExtent` usually default to `[[-∞, -∞], [+∞, +∞]]`
- *to represent an unbounded extent.
+ * to represent an unbounded extent.
  */
 export type CoordinateExtent = [[number, number], [number, number]];