add docs for TLShapeUtil (#1215)

This PR adds docs for the methods in the TLShapeUtil class. I think that it's a good page to have docs on, as it shows people what's possible with the custom shape API. Currently, our docs are not showing `@param` info for lots of methods, including the ones added in this PR. I'll do fix for that in a follow-up PR, so that it's easier to review. --- Note: Moving forward, we probably want to consider **_where_** these docs are shown, and how we achieve that. For example, do we put the docs for these methods in: * The docs page for the `TLShapeUtil` class? * The docs pages for the handler types, eg: [`OnResizeHandler`](http://localhost:3000/gen/editor/OnResizeHandler-type)? * Both? Right now, I opted for putting them in the the TLShapeUtil class, as it keeps them all in one place, and it's what we already do for some others. We should consider both - what works best for the docs? and what works best for code editors? --- This PR also includes a fix to our pre-commit step that @SomeHats did.
2023-05-05 07:05:25 -07:00 · 2023-05-05 07:05:25 -07:00 · b1569c97e0
commit b1569c97e0
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@ -1,6 +1,11 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"

+# if the folder we're in is called "bublic", set YARN_RC_FILENAME:
+if [ "$(basename "$(pwd)")" = "bublic" ]; then
+  export YARN_RC_FILENAME=.yarnrc-private.yml
+fi
+
 npx lazy run build-api
 git add packages/*/api-report.md
 npx lint-staged
--- a/packages/editor/api-report.md
+++ b/packages/editor/api-report.md
@ -1317,7 +1317,7 @@ export type OnBeforeCreateHandler<T extends TLShape> = (next: T) => T | void;
 // @public (undocumented)
 export type OnBeforeUpdateHandler<T extends TLShape> = (prev: T, next: T) => T | void;

-// @public (undocumented)
+// @internal (undocumented)
 export type OnBindingChangeHandler<T extends TLShape> = (shape: T) => TLShapePartial<T> | void;

 // @public (undocumented)
@ -1348,15 +1348,7 @@ export type OnHandleChangeHandler<T extends TLShape> = (shape: T, info: {
 export type OnResizeEndHandler<T extends TLShape> = EventChangeHandler<T>;

 // @public (undocumented)
-export type OnResizeHandler<T extends TLShape> = (shape: T, info: {
-    newPoint: Vec2dModel;
-    handle: TLResizeHandle;
-    mode: TLResizeMode;
-    scaleX: number;
-    scaleY: number;
-    initialBounds: Box2d;
-    initialShape: T;
-}) => Partial<TLShapePartial<T>> | undefined | void;
+export type OnResizeHandler<T extends TLShape> = (shape: T, info: TLResizeInfo<T>) => Partial<TLShapePartial<T>> | undefined | void;

 // @public (undocumented)
 export type OnResizeStartHandler<T extends TLShape> = EventStartHandler<T>;
@ -2389,6 +2381,17 @@ export type TLReorderOperation = 'backward' | 'forward' | 'toBack' | 'toFront';
 // @public (undocumented)
 export type TLResizeHandle = SelectionCorner | SelectionEdge;

+// @public
+export type TLResizeInfo<T extends TLShape> = {
+    newPoint: Vec2dModel;
+    handle: TLResizeHandle;
+    mode: TLResizeMode;
+    scaleX: number;
+    scaleY: number;
+    initialBounds: Box2d;
+    initialShape: T;
+};
+
 // @public
 export type TLResizeMode = 'resize_bounds' | 'scale_shape';

@ -2438,53 +2441,33 @@ export abstract class TLShapeUtil<T extends TLUnknownShape> {
    hitTestLineSegment(shape: T, A: VecLike, B: VecLike): boolean;
    hitTestPoint(shape: T, point: VecLike): boolean;
    abstract indicator(shape: T): any;
-    // (undocumented)
    is(shape: TLBaseShape<string, object>): shape is T;
    isAspectRatioLocked: TLShapeUtilFlag<T>;
    isClosed: TLShapeUtilFlag<T>;
    onBeforeCreate?: OnBeforeCreateHandler<T>;
    onBeforeUpdate?: OnBeforeUpdateHandler<T>;
-    // (undocumented)
+    // @internal
    onBindingChange?: OnBindingChangeHandler<T>;
-    // (undocumented)
    onChildrenChange?: OnChildrenChangeHandler<T>;
-    // (undocumented)
    onClick?: OnClickHandler<T>;
-    // (undocumented)
    onDoubleClick?: OnDoubleClickHandler<T>;
-    // (undocumented)
    onDoubleClickEdge?: OnDoubleClickHandler<T>;
-    // (undocumented)
    onDoubleClickHandle?: OnDoubleClickHandleHandler<T>;
-    // (undocumented)
    onDragShapesOut?: OnDragHandler<T>;
-    // (undocumented)
    onDragShapesOver?: OnDragHandler<T, {
        shouldHint: boolean;
    }>;
-    // (undocumented)
    onDropShapesOver?: OnDragHandler<T>;
-    // (undocumented)
    onEditEnd?: OnEditEndHandler<T>;
-    // (undocumented)
    onHandleChange?: OnHandleChangeHandler<T>;
-    // (undocumented)
    onResize?: OnResizeHandler<T>;
-    // (undocumented)
    onResizeEnd?: OnResizeEndHandler<T>;
-    // (undocumented)
    onResizeStart?: OnResizeStartHandler<T>;
-    // (undocumented)
    onRotate?: OnRotateHandler<T>;
-    // (undocumented)
    onRotateEnd?: OnRotateEndHandler<T>;
-    // (undocumented)
    onRotateStart?: OnRotateStartHandler<T>;
-    // (undocumented)
    onTranslate?: OnTranslateHandler<T>;
-    // (undocumented)
    onTranslateEnd?: OnTranslateEndHandler<T>;
-    // (undocumented)
    onTranslateStart?: OnTranslateStartHandler<T>;
    outline(shape: T): Vec2dModel[];
    point(shape: T): Vec2dModel;
--- a/packages/editor/src/index.ts
+++ b/packages/editor/src/index.ts
@ -56,6 +56,7 @@ export {
 	type OnTranslateEndHandler,
 	type OnTranslateHandler,
 	type OnTranslateStartHandler,
+	type TLResizeInfo,
 	type TLResizeMode,
 	type TLShapeUtilConstructor,
 	type TLShapeUtilFlag,
--- a/packages/editor/src/lib/app/shapeutils/TLShapeUtil.ts
+++ b/packages/editor/src/lib/app/shapeutils/TLShapeUtil.ts
@ -34,6 +34,13 @@ export type TLShapeUtilFlag<T> = (shape: T) => boolean
 export abstract class TLShapeUtil<T extends TLUnknownShape> {
 	constructor(public app: App, public readonly type: T['type']) {}

+	/**
+	 * Check if a shape is of this type.
+	 *
+	 * @param shape - The shape to check.
+	 * @returns Whether the shape is of this type.
+	 * @public
+	 */
 	is(shape: TLBaseShape<string, object>): shape is T {
 		return shape.type === this.type
 	}
@ -371,14 +378,11 @@ export abstract class TLShapeUtil<T extends TLUnknownShape> {
 	 * @example
 	 *
 	 * ```ts
-	 * onBeforeUpdate = (prev, next) => {
-	 * 	if (prev.x === next.x) {
-	 * 		return { ...next, x: next.x + 1 }
-	 * 	}
+	 * onBeforeCreate = (next) => {
+	 * 	return { ...next, x: next.x + 1 }
 	 * }
 	 * ```
 	 *
-	 * @param prev - The previous shape.
 	 * @param next - The next shape.
 	 * @returns The next shape or void.
 	 * @public
@ -406,29 +410,198 @@ export abstract class TLShapeUtil<T extends TLUnknownShape> {
 	 */
 	onBeforeUpdate?: OnBeforeUpdateHandler<T>

+	/**
+	 * A callback called when some other shapes are dragged over this one.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * onDragShapesOver = (shape, shapes) => {
+	 * 	return { shouldHint: true }
+	 * }
+	 * ```
+	 *
+	 * @param shape - The shape.
+	 * @param shapes - The shapes that are being dragged over this one.
+	 * @returns An object specifying whether the shape should hint that it can receive the dragged shapes.
+	 * @public
+	 */
 	onDragShapesOver?: OnDragHandler<T, { shouldHint: boolean }>
+
+	/**
+	 * A callback called when some other shapes are dragged out of this one.
+	 *
+	 * @param shape - The shape.
+	 * @param shapes - The shapes that are being dragged out.
+	 * @public
+	 */
 	onDragShapesOut?: OnDragHandler<T>
+
+	/**
+	 * A callback called when some other shapes are dropped over this one.
+	 *
+	 * @param shape - The shape.
+	 * @param shapes - The shapes that are being dropped over this one.
+	 * @public
+	 */
 	onDropShapesOver?: OnDragHandler<T>

+	/**
+	 * A callback called when a shape starts being resized.
+	 *
+	 * @param shape - The shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onResizeStart?: OnResizeStartHandler<T>
+
+	/**
+	 * A callback called when a shape changes from a resize.
+	 *
+	 * @param shape - The shape at the start of the resize.
+	 * @param info - Info about the resize.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onResize?: OnResizeHandler<T>
+
+	/**
+	 * A callback called when a shape finishes resizing.
+	 *
+	 * @param initial - The shape at the start of the resize.
+	 * @param current - The current shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onResizeEnd?: OnResizeEndHandler<T>

+	/**
+	 * A callback called when a shape starts being translated.
+	 *
+	 * @param shape - The shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onTranslateStart?: OnTranslateStartHandler<T>
+
+	/**
+	 * A callback called when a shape changes from a translation.
+	 *
+	 * @param initial - The shape at the start of the translation.
+	 * @param current - The current shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onTranslate?: OnTranslateHandler<T>
+
+	/**
+	 * A callback called when a shape finishes translating.
+	 *
+	 * @param initial - The shape at the start of the translation.
+	 * @param current - The current shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onTranslateEnd?: OnTranslateEndHandler<T>

+	/**
+	 * A callback called when a shape starts being rotated.
+	 *
+	 * @param shape - The shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onRotateStart?: OnRotateStartHandler<T>
-	onRotateEnd?: OnRotateEndHandler<T>
+
+	/**
+	 * A callback called when a shape changes from a rotation.
+	 *
+	 * @param initial - The shape at the start of the rotation.
+	 * @param current - The current shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onRotate?: OnRotateHandler<T>

+	/**
+	 * A callback called when a shape finishes rotating.
+	 *
+	 * @param initial - The shape at the start of the rotation.
+	 * @param current - The current shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
+	onRotateEnd?: OnRotateEndHandler<T>
+
+	/**
+	 * A callback called when a shape's handle changes.
+	 *
+	 * @param shape - The shape.
+	 * @param info - An object containing the handle and whether the handle is 'precise' or not.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onHandleChange?: OnHandleChangeHandler<T>
+
+	/**
+	 * Not currently used.
+	 *
+	 * @internal
+	 */
 	onBindingChange?: OnBindingChangeHandler<T>
+
+	/**
+	 * A callback called when a shape's children change.
+	 *
+	 * @param shape - The shape.
+	 * @returns An array of shape updates, or void.
+	 * @public
+	 */
 	onChildrenChange?: OnChildrenChangeHandler<T>
+
+	/**
+	 * A callback called when a shape's handle is double clicked.
+	 *
+	 * @param shape - The shape.
+	 * @param handle - The handle that is double-clicked.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onDoubleClickHandle?: OnDoubleClickHandleHandler<T>
+
+	/**
+	 * A callback called when a shape's edge is double clicked.
+	 *
+	 * @param shape - The shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onDoubleClickEdge?: OnDoubleClickHandler<T>
+
+	/**
+	 * A callback called when a shape is double clicked.
+	 *
+	 * @param shape - The shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onDoubleClick?: OnDoubleClickHandler<T>
+
+	/**
+	 * A callback called when a shape is clicked.
+	 *
+	 * @param shape - The shape.
+	 * @returns A change to apply to the shape, or void.
+	 * @public
+	 */
 	onClick?: OnClickHandler<T>
+
+	/**
+	 * A callback called when a shape finishes being editing.
+	 *
+	 * @param shape - The shape.
+	 * @public
+	 */
 	onEditEnd?: OnEditEndHandler<T>
 }

@ -436,14 +609,12 @@ export abstract class TLShapeUtil<T extends TLUnknownShape> {
 export type OnBeforeCreateHandler<T extends TLShape> = (next: T) => T | void
 /** @public */
 export type OnBeforeUpdateHandler<T extends TLShape> = (prev: T, next: T) => T | void
-
 /** @public */
 export type OnTranslateStartHandler<T extends TLShape> = EventStartHandler<T>
 /** @public */
 export type OnTranslateHandler<T extends TLShape> = EventChangeHandler<T>
 /** @public */
 export type OnTranslateEndHandler<T extends TLShape> = EventChangeHandler<T>
-
 /** @public */
 export type OnRotateStartHandler<T extends TLShape> = EventStartHandler<T>
 /** @public */
@ -452,7 +623,10 @@ export type OnRotateHandler<T extends TLShape> = EventChangeHandler<T>
 export type OnRotateEndHandler<T extends TLShape> = EventChangeHandler<T>

 /**
- * TLResizeMode 'scale_shape' - The shape is being scaled, usually as part of a larger selection.
+ * The type of resize.
+ *
+ * 'scale_shape' - The shape is being scaled, usually as part of a larger selection.
+ *
 * 'resize_bounds' - The user is directly manipulating an individual shape's bounds using a resize
 * handle. It is up to shape util implementers to decide how they want to handle the two
 * situations.
@ -460,21 +634,37 @@ export type OnRotateEndHandler<T extends TLShape> = EventChangeHandler<T>
 * @public
 */
 export type TLResizeMode = 'scale_shape' | 'resize_bounds'
+
+/**
+ * Info about a resize.
+ * @param newPoint - The new local position of the shape.
+ * @param handle - The handle being dragged.
+ * @param mode - The type of resize.
+ * @param scaleX - The scale in the x-axis.
+ * @param scaleY - The scale in the y-axis.
+ * @param initialBounds - The bounds of the shape at the start of the resize.
+ * @param initialShape - The shape at the start of the resize.
+ * @public
+ */
+export type TLResizeInfo<T extends TLShape> = {
+	newPoint: Vec2dModel
+	handle: TLResizeHandle
+	mode: TLResizeMode
+	scaleX: number
+	scaleY: number
+	initialBounds: Box2d
+	initialShape: T
+}
+
 /** @public */
 export type OnResizeHandler<T extends TLShape> = (
 	shape: T,
-	info: {
-		newPoint: Vec2dModel
-		handle: TLResizeHandle
-		mode: TLResizeMode
-		scaleX: number
-		scaleY: number
-		initialBounds: Box2d
-		initialShape: T
-	}
+	info: TLResizeInfo<T>
 ) => Partial<TLShapePartial<T>> | undefined | void
+
 /** @public */
 export type OnResizeStartHandler<T extends TLShape> = EventStartHandler<T>
+
 /** @public */
 export type OnResizeEndHandler<T extends TLShape> = EventChangeHandler<T>

@ -483,7 +673,7 @@ export type OnResizeEndHandler<T extends TLShape> = EventChangeHandler<T>
 /** @public */
 export type OnDragHandler<T extends TLShape, R = void> = (shape: T, shapes: TLShape[]) => R

-/** @public */
+/** @internal */
 export type OnBindingChangeHandler<T extends TLShape> = (shape: T) => TLShapePartial<T> | void

 /** @public */