@formicoidea/labre-core 0.23.0

package/src/_pkgs/std/gfx/model/base.ts

@@ -0,0 +1,173 @@
+import type {
+  Bound,
+  IBound,
+  IVec,
+  PointLocation,
+  SerializedXYWH,
+  XYWH,
+} from '../../../global/gfx/index.js';
+
+import type { EditorHost } from '../../view/element/lit-host.js';
+import type { GfxGroupModel, GfxModel } from './model.js';
+
+/**
+ * The methods that a graphic element should implement.
+ * It is already included in the `GfxCompatibleInterface` interface.
+ */
+export interface GfxElementGeometry {
+  containsBound(bound: Bound): boolean;
+  getNearestPoint(point: IVec): IVec;
+  getLineIntersections(start: IVec, end: IVec): PointLocation[] | null;
+  getRelativePointLocation(point: IVec): PointLocation;
+  includesPoint(
+    x: number,
+    y: number,
+    options: PointTestOptions,
+    host: EditorHost
+  ): boolean;
+  intersectsBound(bound: Bound): boolean;
+}
+
+/**
+ * All the model that can be rendered in graphics mode should implement this interface.
+ */
+export interface GfxCompatibleInterface extends IBound, GfxElementGeometry {
+  xywh: SerializedXYWH;
+  index: string;
+
+  /**
+   * Defines the extension of the response area beyond the element's bounding box.
+   * This tuple specifies the horizontal and vertical margins to be added to the element's bound.
+   *
+   * The first value represents the horizontal extension (added to both left and right sides),
+   * and the second value represents the vertical extension (added to both top and bottom sides).
+   *
+   * The response area is computed as:
+   * `[x - horizontal, y - vertical, w + 2 * horizontal, h + 2 * vertical]`.
+   *
+   * Example:
+   * - xywh: `[0, 0, 100, 100]`, `responseExtension: [10, 20]`
+   *   Resulting response area: `[-10, -20, 120, 140]`.
+   * - `responseExtension: [0, 0]` keeps the response area equal to the bounding box.
+   */
+  responseExtension: [number, number];
+
+  readonly group: GfxGroupCompatibleInterface | null;
+
+  readonly groups: GfxGroupCompatibleInterface[];
+
+  readonly deserializedXYWH: XYWH;
+
+  /**
+   * The bound of the element without considering the response extension.
+   */
+  readonly elementBound: Bound;
+
+  /**
+   * The bound of the element considering the response extension.
+   */
+  readonly responseBound: Bound;
+
+  /**
+   * Indicates whether the current block is explicitly locked by self.
+   * For checking the lock status of the element, use `isLocked` instead.
+   * For (un)locking the element, use `(un)lock` instead.
+   */
+  lockedBySelf?: boolean;
+
+  /**
+   * Check if the element is locked. It will check the lock status of the element and its ancestors.
+   */
+  isLocked(): boolean;
+  isLockedBySelf(): boolean;
+  isLockedByAncestor(): boolean;
+
+  lock(): void;
+  unlock(): void;
+
+  /**
+   * Whether to disable fallback rendering for this element, e.g., during zooming.
+   * Defaults to false (fallback to placeholder rendering is enabled).
+   */
+  forceFullRender?: boolean;
+}
+
+/**
+ * The symbol to mark a model as a container.
+ */
+export const gfxGroupCompatibleSymbol = Symbol('GfxGroupCompatible');
+
+/**
+ * Check if the element is a container element.
+ */
+export const isGfxGroupCompatibleModel = (
+  elm: unknown
+): elm is GfxGroupModel => {
+  if (typeof elm !== 'object' || elm === null) return false;
+  return (
+    gfxGroupCompatibleSymbol in elm && elm[gfxGroupCompatibleSymbol] === true
+  );
+};
+
+/**
+ * GfxGroupCompatibleElement is a model that can contain other models.
+ * It just like a group that in common graphic software.
+ */
+export interface GfxGroupCompatibleInterface extends GfxCompatibleInterface {
+  [gfxGroupCompatibleSymbol]: true;
+
+  /**
+   * All child ids of this container.
+   */
+  childIds: string[];
+
+  /**
+   * All child element models of this container.
+   * Note that the `childElements` may not contains all the children in `childIds`,
+   * because some children may not be loaded.
+   */
+  childElements: GfxModel[];
+
+  descendantElements: GfxModel[];
+
+  addChild(element: GfxCompatibleInterface): void;
+  removeChild(element: GfxCompatibleInterface): void;
+  hasChild(element: GfxCompatibleInterface): boolean;
+
+  hasDescendant(element: GfxCompatibleInterface): boolean;
+}
+
+/**
+ * The options for the hit testing of a point.
+ */
+export interface PointTestOptions {
+  /**
+   * The threshold of the hit test. The unit is pixel.
+   */
+  hitThreshold?: number;
+
+  /**
+   * If true, the element bound will be used for the hit testing.
+   * By default, the response bound will be used.
+   */
+  useElementBound?: boolean;
+
+  /**
+   * The padding of the response area for each element when do the hit testing. The unit is pixel.
+   * The first value is the padding for the x-axis, and the second value is the padding for the y-axis.
+   */
+  responsePadding?: [number, number];
+
+  /**
+   * If true, the transparent area of the element will be ignored during the point inclusion test.
+   * Otherwise, the transparent area will be considered as filled area.
+   *
+   * Default is true.
+   */
+  ignoreTransparent?: boolean;
+
+  /**
+   * The zoom level of current view when do the hit testing.
+   */
+  zoom?: number;
+}

package/src/_pkgs/std/gfx/model/gfx-block-model.ts

@@ -0,0 +1,315 @@
+import { BlockSuiteError, ErrorCode } from '../../../global/exceptions/index.js';
+import type { IVec, SerializedXYWH, XYWH } from '../../../global/gfx/index.js';
+import {
+  Bound,
+  deserializeXYWH,
+  getBoundWithRotation,
+  getPointsFromBoundWithRotation,
+  linePolygonIntersects,
+  PointLocation,
+  polygonGetPointTangent,
+  polygonNearestPoint,
+  rotatePoints,
+} from '../../../global/gfx/index.js';
+import type { Constructor } from '../../../global/utils/index.js';
+import { BlockModel } from '../../../store/index.js';
+
+import {
+  isLockedByAncestorImpl,
+  isLockedBySelfImpl,
+  isLockedImpl,
+  lockElementImpl,
+  unlockElementImpl,
+} from '../../utils/tree.js';
+import type { EditorHost } from '../../view/index.js';
+import type { GfxCompatibleInterface, PointTestOptions } from './base.js';
+import type { GfxGroupModel } from './model.js';
+import type { SurfaceBlockModel } from './surface/surface-model.js';
+
+/**
+ * The props that a graphics block model should have.
+ */
+export type GfxCompatibleProps = {
+  xywh: SerializedXYWH;
+  index: string;
+  lockedBySelf?: boolean;
+};
+
+/**
+ * This type include the common props for the graphic block model.
+ * You can use this type with Omit to define the props of a graphic block model.
+ */
+export type GfxCommonBlockProps = GfxCompatibleProps & {
+  rotate: number;
+  scale: number;
+};
+
+/**
+ * The graphic block model that can be rendered in the graphics mode.
+ * All the graphic block model should extend this class.
+ * You can use `GfxCompatibleBlockModel` to convert a BlockModel to a subclass that extends it.
+ */
+export class GfxBlockElementModel<
+    Props extends GfxCompatibleProps = GfxCompatibleProps,
+  >
+  extends BlockModel<Props>
+  implements GfxCompatibleInterface
+{
+  private _cacheDeserKey: string | null = null;
+
+  private _cacheDeserXYWH: XYWH | null = null;
+
+  private _externalXYWH: SerializedXYWH | undefined = undefined;
+
+  connectable = true;
+
+  get xywh() {
+    return this.props.xywh;
+  }
+
+  get xywh$() {
+    return this.props.xywh$;
+  }
+
+  set xywh(xywh: SerializedXYWH) {
+    this.props.xywh = xywh;
+  }
+
+  get index() {
+    return this.props.index;
+  }
+
+  get index$() {
+    return this.props.index$;
+  }
+
+  set index(index: string) {
+    this.props.index = index;
+  }
+
+  get lockedBySelf(): boolean | undefined {
+    return this.props.lockedBySelf;
+  }
+
+  get lockedBySelf$() {
+    return this.props.lockedBySelf$;
+  }
+
+  set lockedBySelf(lockedBySelf: boolean | undefined) {
+    this.props.lockedBySelf = lockedBySelf;
+  }
+
+  /**
+   * Defines the extension of the response area beyond the element's bounding box.
+   * This tuple specifies the horizontal and vertical margins to be added to the element's [x, y, width, height].
+   *
+   * The first value represents the horizontal extension (added to both left and right sides),
+   * and the second value represents the vertical extension (added to both top and bottom sides).
+   *
+   * The response area is computed as:
+   * `[x - horizontal, y - vertical, width + 2 * horizontal, height + 2 * vertical]`.
+   *
+   * Example:
+   * - Bounding box: `[0, 0, 100, 100]`, `responseExtension: [10, 20]`
+   *   Resulting response area: `[-10, -20, 120, 140]`.
+   * - `responseExtension: [0, 0]` keeps the response area equal to the bounding box.
+   */
+  responseExtension: [number, number] = [0, 0];
+
+  get rotate() {
+    if ('rotate' in this.props) {
+      return this.props.rotate as number;
+    }
+
+    return 0;
+  }
+
+  set rotate(rotate: number) {
+    if ('rotate' in this.props) {
+      this.props.rotate = rotate;
+    }
+  }
+
+  get deserializedXYWH() {
+    if (this._cacheDeserKey !== this.xywh || !this._cacheDeserXYWH) {
+      this._cacheDeserKey = this.xywh;
+      this._cacheDeserXYWH = deserializeXYWH(this.xywh);
+    }
+
+    return this._cacheDeserXYWH;
+  }
+
+  get elementBound() {
+    return Bound.from(getBoundWithRotation(this));
+  }
+
+  get externalBound(): Bound | null {
+    return this._externalXYWH ? Bound.deserialize(this._externalXYWH) : null;
+  }
+
+  get externalXYWH(): SerializedXYWH | undefined {
+    return this._externalXYWH;
+  }
+
+  set externalXYWH(xywh: SerializedXYWH | undefined) {
+    this._externalXYWH = xywh;
+  }
+
+  get group(): GfxGroupModel | null {
+    if (!this.surface) return null;
+
+    return this.surface.getGroup(this.id) ?? null;
+  }
+
+  get groups(): GfxGroupModel[] {
+    if (!this.surface) return [];
+
+    return this.surface.getGroups(this.id);
+  }
+
+  get h() {
+    return this.deserializedXYWH[3];
+  }
+
+  get responseBound() {
+    return this.elementBound.expand(this.responseExtension);
+  }
+
+  get surface(): SurfaceBlockModel | null {
+    const result = this.store.getBlocksByFlavour('affine:surface');
+    if (result.length === 0) return null;
+    return result[0].model as SurfaceBlockModel;
+  }
+
+  get w() {
+    return this.deserializedXYWH[2];
+  }
+
+  get x() {
+    return this.deserializedXYWH[0];
+  }
+
+  get y() {
+    return this.deserializedXYWH[1];
+  }
+
+  containsBound(bounds: Bound): boolean {
+    const bound = Bound.deserialize(this.xywh);
+    const points = getPointsFromBoundWithRotation({
+      x: bound.x,
+      y: bound.y,
+      w: bound.w,
+      h: bound.h,
+      rotate: this.rotate,
+    });
+    return points.some(point => bounds.containsPoint(point));
+  }
+
+  getLineIntersections(start: IVec, end: IVec): PointLocation[] | null {
+    const bound = Bound.deserialize(this.xywh);
+
+    return linePolygonIntersects(
+      start,
+      end,
+      rotatePoints(bound.points, bound.center, this.rotate ?? 0)
+    );
+  }
+
+  getNearestPoint(point: IVec): IVec {
+    const bound = Bound.deserialize(this.xywh);
+    return polygonNearestPoint(
+      rotatePoints(bound.points, bound.center, this.rotate ?? 0),
+      point
+    );
+  }
+
+  getRelativePointLocation(relativePoint: IVec): PointLocation {
+    const bound = Bound.deserialize(this.xywh);
+    const point = bound.getRelativePoint(relativePoint);
+    const rotatePoint = rotatePoints(
+      [point],
+      bound.center,
+      this.rotate ?? 0
+    )[0];
+    const points = rotatePoints(bound.points, bound.center, this.rotate ?? 0);
+    const tangent = polygonGetPointTangent(points, rotatePoint);
+
+    return new PointLocation(rotatePoint, tangent);
+  }
+
+  includesPoint(
+    x: number,
+    y: number,
+    opt: PointTestOptions,
+    __: EditorHost
+  ): boolean {
+    const bound = opt.useElementBound ? this.elementBound : this.responseBound;
+    return bound.isPointInBound([x, y], 0);
+  }
+
+  intersectsBound(bound: Bound): boolean {
+    return (
+      this.containsBound(bound) ||
+      bound.points.some((point, i, points) =>
+        this.getLineIntersections(point, points[(i + 1) % points.length])
+      )
+    );
+  }
+
+  isLocked(): boolean {
+    return isLockedImpl(this);
+  }
+
+  isLockedByAncestor(): boolean {
+    return isLockedByAncestorImpl(this);
+  }
+
+  isLockedBySelf(): boolean {
+    return isLockedBySelfImpl(this);
+  }
+
+  lock() {
+    lockElementImpl(this.store, this);
+  }
+
+  unlock() {
+    unlockElementImpl(this.store, this);
+  }
+}
+
+/**
+ * Convert a BlockModel to a GfxBlockElementModel.
+ * @param BlockModelSuperClass The BlockModel class to be converted.
+ * @returns The returned class is a subclass of the GfxBlockElementModel class and the given BlockModelSuperClass.
+ */
+export function GfxCompatibleBlockModel<
+  Props extends GfxCompatibleProps,
+  T extends Constructor<BlockModel<Props>> = Constructor<BlockModel<Props>>,
+>(BlockModelSuperClass: T) {
+  if (BlockModelSuperClass === BlockModel) {
+    return GfxBlockElementModel as unknown as typeof GfxBlockElementModel<Props>;
+  } else {
+    let currentClass = BlockModelSuperClass;
+
+    while (
+      Object.getPrototypeOf(currentClass.prototype) !== BlockModel.prototype &&
+      Object.getPrototypeOf(currentClass.prototype) !== null
+    ) {
+      currentClass = Object.getPrototypeOf(currentClass.prototype).constructor;
+    }
+
+    if (Object.getPrototypeOf(currentClass.prototype) === null) {
+      throw new BlockSuiteError(
+        ErrorCode.GfxBlockElementError,
+        'The SuperClass is not a subclass of BlockModel'
+      );
+    }
+
+    Object.setPrototypeOf(
+      currentClass.prototype,
+      GfxBlockElementModel.prototype
+    );
+  }
+
+  return BlockModelSuperClass as unknown as typeof GfxBlockElementModel<Props>;
+}

package/src/_pkgs/std/gfx/model/model.ts

@@ -0,0 +1,18 @@
+import type { GfxGroupCompatibleInterface } from './base.js';
+import type { GfxBlockElementModel } from './gfx-block-model.js';
+import {
+  type GfxGroupLikeElementModel,
+  GfxPrimitiveElementModel,
+} from './surface/element-model.js';
+
+export type GfxModel = GfxBlockElementModel | GfxPrimitiveElementModel;
+
+export type GfxGroupModel =
+  | (GfxGroupCompatibleInterface & GfxBlockElementModel)
+  | GfxGroupLikeElementModel;
+
+export const isPrimitiveModel = (
+  model: GfxModel
+): model is GfxPrimitiveElementModel => {
+  return model instanceof GfxPrimitiveElementModel;
+};

package/src/_pkgs/std/gfx/model/surface/decorators/common.ts

@@ -0,0 +1,53 @@
+import type { SurfaceBlockModel } from '../surface-model.js';
+
+/**
+ * Set metadata for a property
+ * @param symbol Unique symbol for the metadata
+ * @param target The target object to set metadata on, usually the prototype
+ * @param prop The property name
+ * @param val The value to set
+ */
+export function setObjectPropMeta(
+  symbol: symbol,
+  target: unknown,
+  prop: string | symbol,
+  val: unknown
+) {
+  // @ts-expect-error ignore
+  target[symbol] = target[symbol] ?? {};
+  // @ts-expect-error ignore
+  target[symbol][prop] = val;
+}
+
+/**
+ * Get metadata for a property
+ * @param target The target object to retrieve metadata from, usually the prototype
+ * @param symbol Unique symbol for the metadata
+ * @param prop The property name, if not provided, returns all metadata for that symbol
+ * @returns
+ */
+export function getObjectPropMeta(
+  target: unknown,
+  symbol: symbol,
+  prop?: string | symbol
+) {
+  if (prop) {
+    // @ts-expect-error ignore
+    return target[symbol]?.[prop] ?? null;
+  }
+
+  // @ts-expect-error ignore
+  return target[symbol] ?? {};
+}
+
+export function getDecoratorState(surface: SurfaceBlockModel) {
+  return surface['_decoratorState'];
+}
+
+export function createDecoratorState() {
+  return {
+    creating: false,
+    deriving: false,
+    skipField: false,
+  };
+}

package/src/_pkgs/std/gfx/model/surface/decorators/convert.ts

@@ -0,0 +1,49 @@
+import type { GfxPrimitiveElementModel } from '../element-model.js';
+import { getObjectPropMeta, setObjectPropMeta } from './common.js';
+
+const convertSymbol = Symbol('convert');
+
+/**
+ * The convert decorator is used to convert the property value before it's
+ * set to the Y map.
+ *
+ * Note:
+ * 1. This decorator function will not execute in model initialization.
+ * @param fn
+ * @returns
+ */
+export function convert<V, T extends GfxPrimitiveElementModel>(
+  fn: (propValue: V, instance: T) => unknown
+) {
+  return function convertDecorator(
+    _: unknown,
+    context: ClassAccessorDecoratorContext
+  ) {
+    const prop = String(context.name);
+    return {
+      init(this: T, v: V) {
+        const proto = Object.getPrototypeOf(this);
+        setObjectPropMeta(convertSymbol, proto, prop, fn);
+        return v;
+      },
+    } as ClassAccessorDecoratorResult<T, V>;
+  };
+}
+
+function getConvertMeta(
+  proto: unknown,
+  prop: string | symbol
+): null | ((propValue: unknown, instance: unknown) => unknown) {
+  return getObjectPropMeta(proto, convertSymbol, prop);
+}
+
+export function convertProps(
+  propName: string | symbol,
+  propValue: unknown,
+  receiver: unknown
+) {
+  const proto = Object.getPrototypeOf(receiver);
+  const convertFn = getConvertMeta(proto, propName as string)!;
+
+  return convertFn ? convertFn(propValue, receiver) : propValue;
+}

package/src/_pkgs/std/gfx/model/surface/decorators/derive.ts

@@ -0,0 +1,103 @@
+import type { GfxPrimitiveElementModel } from '../element-model.js';
+import {
+  getDecoratorState,
+  getObjectPropMeta,
+  setObjectPropMeta,
+} from './common.js';
+
+const deriveSymbol = Symbol('derive');
+
+const keys = Object.keys;
+
+function getDerivedMeta(
+  proto: unknown,
+  prop: string | symbol
+):
+  | null
+  | ((propValue: unknown, instance: unknown) => Record<string, unknown>)[] {
+  return getObjectPropMeta(proto, deriveSymbol, prop);
+}
+
+export function getDerivedProps(
+  prop: string | symbol,
+  propValue: unknown,
+  receiver: GfxPrimitiveElementModel
+) {
+  const prototype = Object.getPrototypeOf(receiver);
+  const decoratorState = getDecoratorState(receiver.surface);
+
+  if (decoratorState.deriving || decoratorState.creating) {
+    return null;
+  }
+
+  const deriveFns = getDerivedMeta(prototype, prop as string)!;
+
+  return deriveFns
+    ? deriveFns.reduce(
+        (derivedProps, fn) => {
+          const props = fn(propValue, receiver);
+
+          Object.entries(props).forEach(([key, value]) => {
+            derivedProps[key] = value;
+          });
+
+          return derivedProps;
+        },
+        {} as Record<string, unknown>
+      )
+    : null;
+}
+
+export function updateDerivedProps(
+  derivedProps: Record<string, unknown> | null,
+  receiver: GfxPrimitiveElementModel
+) {
+  if (derivedProps) {
+    const decoratorState = getDecoratorState(receiver.surface);
+    decoratorState.deriving = true;
+    keys(derivedProps).forEach(key => {
+      // @ts-expect-error ignore
+      receiver[key] = derivedProps[key];
+    });
+    decoratorState.deriving = false;
+  }
+}
+
+/**
+ * The derive decorator is used to derive other properties' update when the
+ * decorated property is updated through assignment in the local.
+ *
+ * Note:
+ * 1. The first argument of the function is the new value of the decorated property
+ *    before the `convert` decorator is called.
+ * 2. The decorator function will execute after the decorated property has been updated.
+ * 3. The decorator function will not execute during model creation.
+ * 4. The decorator function will not execute if the decorated property is updated through
+ *    the Y map. That is to say, if other peers update the property will not trigger this decorator
+ * @param fn
+ * @returns
+ */
+export function derive<V, T extends GfxPrimitiveElementModel>(
+  fn: (propValue: any, instance: T) => Record<string, unknown>
+) {
+  return function deriveDecorator(
+    _: unknown,
+    context: ClassAccessorDecoratorContext
+  ) {
+    const prop = String(context.name);
+    return {
+      init(this: GfxPrimitiveElementModel, v: V) {
+        const proto = Object.getPrototypeOf(this);
+        const derived = getDerivedMeta(proto, prop);
+
+        if (Array.isArray(derived)) {
+          derived.push(fn as (typeof derived)[0]);
+        } else {
+          setObjectPropMeta(deriveSymbol, proto, prop as string, [fn]);
+        }
+
+        return v;
+      },
+    } as ClassAccessorDecoratorResult<GfxPrimitiveElementModel, V>;
+  };
+}