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.

.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

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

packages/editor/src/index.ts

@@ -56,6 +56,7 @@ export {
 	type OnTranslateEndHandler,
 	type OnTranslateHandler,
 	type OnTranslateStartHandler,
+	type TLResizeInfo,
 	type TLResizeMode,
 	type TLShapeUtilConstructor,
 	type TLShapeUtilFlag,

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) => {
+	 * onBeforeCreate = (next) => {
-	 * 	if (prev.x === next.x) {
+	 * 	return { ...next, x: next.x + 1 }
-	 * 		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: {
+	info: TLResizeInfo<T>
-		newPoint: Vec2dModel
-		handle: TLResizeHandle
-		mode: TLResizeMode
-		scaleX: number
-		scaleY: number
-		initialBounds: Box2d
-		initialShape: 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 */