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.
This commit is contained in:
parent
880f82e658
commit
b1569c97e0
4 changed files with 229 additions and 50 deletions
|
@ -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
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -56,6 +56,7 @@ export {
|
|||
type OnTranslateEndHandler,
|
||||
type OnTranslateHandler,
|
||||
type OnTranslateStartHandler,
|
||||
type TLResizeInfo,
|
||||
type TLResizeMode,
|
||||
type TLShapeUtilConstructor,
|
||||
type TLShapeUtilFlag,
|
||||
|
|
|
@ -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 */
|
||||
|
|
Loading…
Reference in a new issue