@pooder/kit 5.3.0 → 5.4.0

package/src/services/CanvasService.ts

@@ -1,12 +1,56 @@
-import { Canvas, Group, FabricObject, Rect, Path, Image } from "fabric";
+import { Canvas, Group, FabricObject, Rect, Path, Image, Text } from "fabric";
 import { Service, EventBus } from "@pooder/core";
 import { ViewportSystem } from "./ViewportSystem";
-import type { RenderLayerSpec, RenderObjectSpec } from "./renderSpec";
+import type {
+  RenderCoordinateSpace,
+  RenderLayerSpec,
+  RenderLayoutInsets,
+  RenderLayoutLength,
+  RenderObjectLayoutSpec,
+  RenderObjectSpec,
+} from "./renderSpec";
+
+export interface RenderProducerResult {
+  layerSpecs?: Record<string, RenderObjectSpec[]>;
+  rootLayerSpecs?: Record<string, RenderObjectSpec[]>;
+  replaceLayerIds?: string[];
+  replaceRootLayerIds?: string[];
+}
+
+export type RenderProducer = () =>
+  | RenderProducerResult
+  | undefined
+  | Promise<RenderProducerResult | undefined>;
+
+export interface RegisterRenderProducerOptions {
+  priority?: number;
+}
+
+interface RenderProducerEntry {
+  toolId: string;
+  producer: RenderProducer;
+  priority: number;
+  order: number;
+}
+
+interface RectLike {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
 
 export default class CanvasService implements Service {
   public canvas: Canvas;
   public viewport: ViewportSystem;
   private eventBus?: EventBus;
+  private renderProducers: Map<string, RenderProducerEntry> = new Map();
+  private producerOrder = 0;
+  private producerFlushRequested = false;
+  private producerLoopPending = false;
+  private producerLoopPromise: Promise<void> | null = null;
+  private managedProducerLayerIds: Set<string> = new Set();
+  private managedProducerRootLayerIds: Set<string> = new Set();
 
   constructor(el: HTMLCanvasElement | string | Canvas, options?: any) {
     if (el instanceof Canvas) {
@@ -22,7 +66,7 @@ export default class CanvasService implements Service {
     if (this.canvas.width !== undefined && this.canvas.height !== undefined) {
       this.viewport.updateContainer(this.canvas.width, this.canvas.height);
     }
-    
+
     if (options?.eventBus) {
       this.setEventBus(options.eventBus);
     }
@@ -48,9 +92,185 @@ export default class CanvasService implements Service {
   }
 
   dispose() {
+    this.renderProducers.clear();
+    this.managedProducerLayerIds.clear();
+    this.managedProducerRootLayerIds.clear();
+    this.producerFlushRequested = false;
     this.canvas.dispose();
   }
 
+  registerRenderProducer(
+    toolId: string,
+    producer: RenderProducer,
+    options: RegisterRenderProducerOptions = {},
+  ): { dispose: () => void } {
+    const normalizedToolId = String(toolId || "").trim();
+    if (!normalizedToolId) {
+      throw new Error(
+        "[CanvasService] registerRenderProducer requires a toolId.",
+      );
+    }
+    if (typeof producer !== "function") {
+      throw new Error(
+        `[CanvasService] registerRenderProducer("${normalizedToolId}") requires a producer function.`,
+      );
+    }
+    const entry: RenderProducerEntry = {
+      toolId: normalizedToolId,
+      producer,
+      priority: Number.isFinite(options.priority)
+        ? Number(options.priority)
+        : 0,
+      order: this.producerOrder++,
+    };
+    this.renderProducers.set(normalizedToolId, entry);
+    this.requestRenderFromProducers();
+    return {
+      dispose: () => {
+        this.unregisterRenderProducer(normalizedToolId);
+      },
+    };
+  }
+
+  unregisterRenderProducer(toolId: string): boolean {
+    const normalizedToolId = String(toolId || "").trim();
+    if (!normalizedToolId) return false;
+    const removed = this.renderProducers.delete(normalizedToolId);
+    if (removed) {
+      this.requestRenderFromProducers();
+    }
+    return removed;
+  }
+
+  requestRenderFromProducers() {
+    this.producerFlushRequested = true;
+    this.scheduleProducerLoop();
+  }
+
+  async flushRenderFromProducers(): Promise<void> {
+    this.requestRenderFromProducers();
+    if (this.producerLoopPromise) {
+      await this.producerLoopPromise;
+    }
+  }
+
+  private scheduleProducerLoop() {
+    if (this.producerLoopPending) return;
+    this.producerLoopPending = true;
+    this.producerLoopPromise = Promise.resolve()
+      .then(() => this.runProducerLoop())
+      .catch((error) => {
+        console.error("[CanvasService] render producer loop failed.", error);
+      })
+      .finally(() => {
+        this.producerLoopPending = false;
+        if (this.producerFlushRequested) {
+          this.scheduleProducerLoop();
+        }
+      });
+  }
+
+  private async runProducerLoop(): Promise<void> {
+    while (this.producerFlushRequested) {
+      this.producerFlushRequested = false;
+      await this.collectAndApplyProducerSpecs();
+    }
+  }
+
+  private sortedRenderProducerEntries(): RenderProducerEntry[] {
+    return Array.from(this.renderProducers.values()).sort((a, b) => {
+      if (a.priority !== b.priority) {
+        return a.priority - b.priority;
+      }
+      if (a.order !== b.order) {
+        return a.order - b.order;
+      }
+      return a.toolId.localeCompare(b.toolId);
+    });
+  }
+
+  private appendLayerSpecMap(
+    map: Map<string, RenderObjectSpec[]>,
+    source?: Record<string, RenderObjectSpec[]>,
+  ) {
+    if (!source) return;
+    Object.entries(source).forEach(([layerId, specs]) => {
+      if (!Array.isArray(specs)) return;
+      const list = map.get(layerId) || [];
+      list.push(...specs);
+      map.set(layerId, list);
+    });
+  }
+
+  private async collectAndApplyProducerSpecs(): Promise<void> {
+    const groupLayerSpecs = new Map<string, RenderObjectSpec[]>();
+    const rootLayerSpecs = new Map<string, RenderObjectSpec[]>();
+    const replaceLayerIds = new Set<string>();
+    const replaceRootLayerIds = new Set<string>();
+    const entries = this.sortedRenderProducerEntries();
+
+    for (const entry of entries) {
+      try {
+        const result = await entry.producer();
+        if (!result) continue;
+        this.appendLayerSpecMap(groupLayerSpecs, result.layerSpecs);
+        this.appendLayerSpecMap(rootLayerSpecs, result.rootLayerSpecs);
+        if (Array.isArray(result.replaceLayerIds)) {
+          result.replaceLayerIds.forEach((layerId) => {
+            if (layerId) replaceLayerIds.add(layerId);
+          });
+        }
+        if (Array.isArray(result.replaceRootLayerIds)) {
+          result.replaceRootLayerIds.forEach((layerId) => {
+            if (layerId) replaceRootLayerIds.add(layerId);
+          });
+        }
+      } catch (error) {
+        console.error(
+          `[CanvasService] render producer "${entry.toolId}" failed.`,
+          error,
+        );
+      }
+    }
+
+    const nextLayerIds = new Set(groupLayerSpecs.keys());
+    const nextRootLayerIds = new Set(rootLayerSpecs.keys());
+
+    for (const [layerId, specs] of groupLayerSpecs.entries()) {
+      if (replaceLayerIds.has(layerId)) {
+        const layer = this.getLayer(layerId);
+        if (layer) {
+          (layer.getObjects() as any[]).forEach((obj) => layer.remove(obj));
+        }
+      }
+      await this.applyObjectSpecsToLayer(layerId, specs, { render: false });
+    }
+
+    for (const layerId of this.managedProducerLayerIds) {
+      if (nextLayerIds.has(layerId)) continue;
+      const layer = this.getLayer(layerId);
+      if (!layer) continue;
+      await this.applyObjectSpecsToContainer(layer, [], { render: false });
+    }
+
+    for (const [layerId, specs] of rootLayerSpecs.entries()) {
+      if (replaceRootLayerIds.has(layerId)) {
+        const existing = this.getRootLayerObjects(layerId) as any[];
+        existing.forEach((obj) => this.canvas.remove(obj));
+      }
+      await this.applyObjectSpecsToRootLayer(layerId, specs, { render: false });
+    }
+
+    for (const layerId of this.managedProducerRootLayerIds) {
+      if (nextRootLayerIds.has(layerId)) continue;
+      await this.applyObjectSpecsToRootLayer(layerId, [], { render: false });
+    }
+
+    this.managedProducerLayerIds = nextLayerIds;
+    this.managedProducerRootLayerIds = nextRootLayerIds;
+    this.requestRenderAll();
+  }
+
   /**
    * Get a layer (Group) by its ID.
    * We assume layers are Groups directly on the canvas with a data.id property.
@@ -102,6 +322,268 @@ export default class CanvasService implements Service {
     this.requestRenderAll();
   }
 
+  getSceneScale(): number {
+    const scale = Number(this.viewport.scale);
+    return Number.isFinite(scale) && scale > 0 ? scale : 1;
+  }
+
+  getSceneOffset(): { x: number; y: number } {
+    const offset = this.viewport.offset;
+    const x = Number(offset.x);
+    const y = Number(offset.y);
+    return {
+      x: Number.isFinite(x) ? x : 0,
+      y: Number.isFinite(y) ? y : 0,
+    };
+  }
+
+  toScreenPoint(point: { x: number; y: number }): { x: number; y: number } {
+    const scale = this.getSceneScale();
+    const offset = this.getSceneOffset();
+    return {
+      x: point.x * scale + offset.x,
+      y: point.y * scale + offset.y,
+    };
+  }
+
+  toScenePoint(point: { x: number; y: number }): { x: number; y: number } {
+    const scale = this.getSceneScale();
+    const offset = this.getSceneOffset();
+    return {
+      x: (point.x - offset.x) / scale,
+      y: (point.y - offset.y) / scale,
+    };
+  }
+
+  toScreenLength(value: number): number {
+    return value * this.getSceneScale();
+  }
+
+  toSceneLength(value: number): number {
+    return value / this.getSceneScale();
+  }
+
+  toScreenRect(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  }): { left: number; top: number; width: number; height: number } {
+    const start = this.toScreenPoint({ x: rect.left, y: rect.top });
+    return {
+      left: start.x,
+      top: start.y,
+      width: this.toScreenLength(rect.width),
+      height: this.toScreenLength(rect.height),
+    };
+  }
+
+  toSceneRect(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  }): { left: number; top: number; width: number; height: number } {
+    const start = this.toScenePoint({ x: rect.left, y: rect.top });
+    return {
+      left: start.x,
+      top: start.y,
+      width: this.toSceneLength(rect.width),
+      height: this.toSceneLength(rect.height),
+    };
+  }
+
+  getSceneViewportRect(): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  } {
+    const width = Number(this.canvas.width || 0);
+    const height = Number(this.canvas.height || 0);
+    return this.toSceneRect({ left: 0, top: 0, width, height });
+  }
+
+  getScreenViewportRect(): RectLike {
+    return {
+      left: 0,
+      top: 0,
+      width: Number(this.canvas.width || 0),
+      height: Number(this.canvas.height || 0),
+    };
+  }
+
+  private toSpaceRect(
+    rect: RectLike,
+    from: RenderCoordinateSpace,
+    to: RenderCoordinateSpace,
+  ): RectLike {
+    if (from === to) return { ...rect };
+    if (from === "scene") {
+      return this.toScreenRect(rect);
+    }
+    return this.toSceneRect(rect);
+  }
+
+  private resolveLayoutLength(
+    value: RenderLayoutLength | undefined,
+    base: number,
+  ): number | undefined {
+    if (typeof value === "number") {
+      return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value !== "string") {
+      return undefined;
+    }
+    const raw = value.trim();
+    if (!raw) return undefined;
+    if (raw.endsWith("%")) {
+      const percent = parseFloat(raw.slice(0, -1));
+      if (!Number.isFinite(percent)) return undefined;
+      return (base * percent) / 100;
+    }
+    const parsed = parseFloat(raw);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+
+  private resolveLayoutInsets(
+    inset: RenderLayoutLength | RenderLayoutInsets | undefined,
+    reference: RectLike,
+  ): { top: number; right: number; bottom: number; left: number } {
+    if (typeof inset === "number" || typeof inset === "string") {
+      const all =
+        this.resolveLayoutLength(
+          inset,
+          Math.min(reference.width, reference.height),
+        ) ?? 0;
+      return { top: all, right: all, bottom: all, left: all };
+    }
+
+    const source = inset || {};
+    const top = this.resolveLayoutLength(source.top, reference.height) ?? 0;
+    const right = this.resolveLayoutLength(source.right, reference.width) ?? 0;
+    const bottom =
+      this.resolveLayoutLength(source.bottom, reference.height) ?? 0;
+    const left = this.resolveLayoutLength(source.left, reference.width) ?? 0;
+    return { top, right, bottom, left };
+  }
+
+  private resolveLayoutReferenceRect(
+    layout: RenderObjectLayoutSpec,
+    space: RenderCoordinateSpace,
+  ): RectLike {
+    if (layout.referenceRect) {
+      const sourceSpace: RenderCoordinateSpace =
+        layout.referenceRect.space || space;
+      return this.toSpaceRect(layout.referenceRect, sourceSpace, space);
+    }
+
+    const reference = layout.reference || "sceneViewport";
+    if (reference === "screenViewport") {
+      const screenRect = this.getScreenViewportRect();
+      return space === "screen" ? screenRect : this.toSceneRect(screenRect);
+    }
+
+    const sceneRect = this.getSceneViewportRect();
+    return space === "scene" ? sceneRect : this.toScreenRect(sceneRect);
+  }
+
+  private alignFactor(value: unknown): number {
+    if (value === "end") return 1;
+    if (value === "center") return 0.5;
+    return 0;
+  }
+
+  private normalizeOriginX(value: unknown): "left" | "center" | "right" {
+    if (value === "center") return "center";
+    if (value === "right") return "right";
+    return "left";
+  }
+
+  private normalizeOriginY(value: unknown): "top" | "center" | "bottom" {
+    if (value === "center") return "center";
+    if (value === "bottom") return "bottom";
+    return "top";
+  }
+
+  private originFactor(
+    value: "left" | "center" | "right" | "top" | "bottom",
+  ): number {
+    if (value === "center") return 0.5;
+    if (value === "right" || value === "bottom") return 1;
+    return 0;
+  }
+
+  private resolveLayoutProps(
+    spec: RenderObjectSpec,
+    props: Record<string, any>,
+  ): Record<string, any> {
+    const layout = spec.layout;
+    if (!layout) {
+      return { ...props };
+    }
+
+    const space: RenderCoordinateSpace = spec.space || "scene";
+    const reference = this.resolveLayoutReferenceRect(layout, space);
+    const inset = this.resolveLayoutInsets(layout.inset, reference);
+    const area: RectLike = {
+      left: reference.left + inset.left,
+      top: reference.top + inset.top,
+      width: Math.max(0, reference.width - inset.left - inset.right),
+      height: Math.max(0, reference.height - inset.top - inset.bottom),
+    };
+
+    const next = { ...props };
+    const width =
+      this.resolveLayoutLength(layout.width, area.width) ??
+      (Number.isFinite(next.width) ? Number(next.width) : undefined);
+    const height =
+      this.resolveLayoutLength(layout.height, area.height) ??
+      (Number.isFinite(next.height) ? Number(next.height) : undefined);
+
+    if (width !== undefined) next.width = width;
+    if (height !== undefined) next.height = height;
+
+    const alignX = this.alignFactor(layout.alignX);
+    const alignY = this.alignFactor(layout.alignY);
+    const offsetX = this.resolveLayoutLength(layout.offsetX, area.width) ?? 0;
+    const offsetY = this.resolveLayoutLength(layout.offsetY, area.height) ?? 0;
+    const objectWidth = Number.isFinite(next.width) ? Number(next.width) : 0;
+    const objectHeight = Number.isFinite(next.height) ? Number(next.height) : 0;
+
+    const objectLeft =
+      area.left + (area.width - objectWidth) * alignX + offsetX;
+    const objectTop =
+      area.top + (area.height - objectHeight) * alignY + offsetY;
+
+    const originX = this.normalizeOriginX(next.originX);
+    const originY = this.normalizeOriginY(next.originY);
+    next.left = objectLeft + objectWidth * this.originFactor(originX);
+    next.top = objectTop + objectHeight * this.originFactor(originY);
+    return next;
+  }
+
+  setLayerVisibility(layerId: string, visible: boolean) {
+    const layer = this.getLayer(layerId);
+    if (layer) {
+      layer.set({ visible });
+    }
+    const objects = this.getRootLayerObjects(layerId) as any[];
+    objects.forEach((obj) => {
+      obj.set?.({ visible });
+      obj.setCoords?.();
+    });
+  }
+
+  bringLayerToFront(layerId: string) {
+    const layer = this.getLayer(layerId);
+    if (layer) {
+      this.canvas.bringObjectToFront(layer);
+    }
+    const objects = this.getRootLayerObjects(layerId) as any[];
+    objects.forEach((obj) => this.canvas.bringObjectToFront(obj as any));
+  }
+
   async applyLayerSpec(spec: RenderLayerSpec): Promise<void> {
     const layer = this.createLayer(spec.id, spec.props || {});
     await this.applyObjectSpecsToContainer(layer, spec.objects);
@@ -110,9 +592,10 @@ export default class CanvasService implements Service {
   async applyObjectSpecsToLayer(
     layerId: string,
     objects: RenderObjectSpec[],
+    options: { render?: boolean } = {},
   ): Promise<void> {
     const layer = this.createLayer(layerId, {});
-    await this.applyObjectSpecsToContainer(layer, objects);
+    await this.applyObjectSpecsToContainer(layer, objects, options);
   }
 
   getRootLayerObjects(layerId: string): FabricObject[] {
@@ -124,6 +607,7 @@ export default class CanvasService implements Service {
   async applyObjectSpecsToRootLayer(
     layerId: string,
     specs: RenderObjectSpec[],
+    options: { render?: boolean } = {},
   ): Promise<void> {
     const desiredIds = new Set(specs.map((s) => s.id));
     const existing = this.getRootLayerObjects(layerId) as any[];
@@ -167,12 +651,15 @@ export default class CanvasService implements Service {
       this.patchFabricObject(current, spec, { layerId });
     }
 
-    this.requestRenderAll();
+    if (options.render !== false) {
+      this.requestRenderAll();
+    }
   }
 
   private async applyObjectSpecsToContainer(
     container: Group,
     specs: RenderObjectSpec[],
+    options: { render?: boolean } = {},
   ): Promise<void> {
     const desiredIds = new Set(specs.map((s) => s.id));
     const existing = container.getObjects() as any[];
@@ -218,7 +705,9 @@ export default class CanvasService implements Service {
     }
 
     container.dirty = true;
-    this.requestRenderAll();
+    if (options.render !== false) {
+      this.requestRenderAll();
+    }
   }
 
   private patchFabricObject(
@@ -232,10 +721,38 @@ export default class CanvasService implements Service {
       ...(extraData || {}),
       id: spec.id,
     };
-    obj.set({ ...(spec.props || {}), data: nextData });
+    const props = this.resolveFabricProps(spec, spec.props || {});
+    obj.set({ ...props, data: nextData });
     obj.setCoords();
   }
 
+  private resolveFabricProps(
+    spec: RenderObjectSpec,
+    props: Record<string, any>,
+  ): Record<string, any> {
+    const space: RenderCoordinateSpace = spec.space || "scene";
+    const next = this.resolveLayoutProps(spec, props);
+    if (space === "screen") {
+      return next;
+    }
+    const hasLeft = Number.isFinite(next.left);
+    const hasTop = Number.isFinite(next.top);
+    if (hasLeft || hasTop) {
+      const mapped = this.toScreenPoint({
+        x: hasLeft ? Number(next.left) : 0,
+        y: hasTop ? Number(next.top) : 0,
+      });
+      if (hasLeft) next.left = mapped.x;
+      if (hasTop) next.top = mapped.y;
+    }
+    const rawScaleX = Number.isFinite(next.scaleX) ? Number(next.scaleX) : 1;
+    const rawScaleY = Number.isFinite(next.scaleY) ? Number(next.scaleY) : 1;
+    const sceneScale = this.getSceneScale();
+    next.scaleX = rawScaleX * sceneScale;
+    next.scaleY = rawScaleY * sceneScale;
+    return next;
+  }
+
   private moveObjectInContainer(
     container: Group | Canvas,
     obj: any,
@@ -265,8 +782,9 @@ export default class CanvasService implements Service {
     spec: RenderObjectSpec,
   ): Promise<FabricObject | undefined> {
     if (spec.type === "rect") {
+      const props = this.resolveFabricProps(spec, spec.props || {});
       const rect = new Rect({
-        ...(spec.props || {}),
+        ...props,
         data: { ...(spec.data || {}), id: spec.id },
       } as any);
       rect.setCoords();
@@ -274,10 +792,12 @@ export default class CanvasService implements Service {
     }
 
     if (spec.type === "path") {
-      const pathData = (spec.props as any)?.path || (spec.props as any)?.pathData;
+      const pathData =
+        (spec.props as any)?.path || (spec.props as any)?.pathData;
       if (!pathData) return undefined;
+      const props = this.resolveFabricProps(spec, spec.props || {});
       const path = new Path(pathData, {
-        ...(spec.props || {}),
+        ...props,
         data: { ...(spec.data || {}), id: spec.id },
       } as any);
       path.setCoords();
@@ -287,14 +807,26 @@ export default class CanvasService implements Service {
     if (spec.type === "image") {
       if (!spec.src) return undefined;
       const image = await Image.fromURL(spec.src, { crossOrigin: "anonymous" });
+      const props = this.resolveFabricProps(spec, spec.props || {});
       image.set({
-        ...(spec.props || {}),
+        ...props,
         data: { ...(spec.data || {}), id: spec.id },
       } as any);
       image.setCoords();
       return image as any;
     }
 
+    if (spec.type === "text") {
+      const content = String((spec.props as any)?.text ?? "");
+      const props = this.resolveFabricProps(spec, spec.props || {});
+      const text = new Text(content, {
+        ...props,
+        data: { ...(spec.data || {}), id: spec.id },
+      } as any);
+      text.setCoords();
+      return text as any;
+    }
+
     return undefined;
   }
 }

package/src/services/renderSpec.ts

@@ -1,6 +1,40 @@
-export type RenderObjectType = "rect" | "image" | "path";
+export type RenderObjectType = "rect" | "image" | "path" | "text";
 
 export type RenderProps = Record<string, any>;
+export type RenderCoordinateSpace = "scene" | "screen";
+export type RenderLayoutLength = number | string;
+export type RenderLayoutAlign = "start" | "center" | "end";
+export type RenderLayoutReference =
+  | "sceneViewport"
+  | "screenViewport"
+  | "custom";
+
+export interface RenderLayoutInsets {
+  top?: RenderLayoutLength;
+  right?: RenderLayoutLength;
+  bottom?: RenderLayoutLength;
+  left?: RenderLayoutLength;
+}
+
+export interface RenderLayoutRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  space?: RenderCoordinateSpace;
+}
+
+export interface RenderObjectLayoutSpec {
+  reference?: RenderLayoutReference;
+  referenceRect?: RenderLayoutRect;
+  inset?: RenderLayoutLength | RenderLayoutInsets;
+  alignX?: RenderLayoutAlign;
+  alignY?: RenderLayoutAlign;
+  offsetX?: RenderLayoutLength;
+  offsetY?: RenderLayoutLength;
+  width?: RenderLayoutLength;
+  height?: RenderLayoutLength;
+}
 
 export interface RenderObjectSpec {
   id: string;
@@ -8,6 +42,8 @@ export interface RenderObjectSpec {
   props: RenderProps;
   data?: Record<string, any>;
   src?: string;
+  space?: RenderCoordinateSpace;
+  layout?: RenderObjectLayoutSpec;
 }
 
 export interface RenderLayerSpec {
@@ -15,4 +51,3 @@ export interface RenderLayerSpec {
   objects: RenderObjectSpec[];
   props?: RenderProps;
 }
-