@pooder/kit 3.4.0 → 4.0.0

package/src/geometry.ts

@@ -1,98 +1,23 @@
 import paper from "paper";
 
-export type PositionAnchor =
-  | "top-left"
-  | "top-center"
-  | "top-right"
-  | "center-left"
-  | "center"
-  | "center-right"
-  | "bottom-left"
-  | "bottom-center"
-  | "bottom-right";
-
-export interface HoleData {
-  x?: number;
-  y?: number;
-  shape?: "circle" | "square";
-  anchor?: PositionAnchor;
-  offsetX?: number;
-  offsetY?: number;
-  innerRadius: number;
-  outerRadius: number;
-}
-
-export function resolveHolePosition(
-  hole: HoleData,
-  geometry: { x: number; y: number; width: number; height: number },
-  canvasSize: { width: number; height: number },
-): { x: number; y: number } {
-  if (hole.anchor) {
-    const { x, y, width, height } = geometry;
-    let bx = x; // center x
-    let by = y; // center y
-
-    // Calculate anchor base position based on shape bounds
-    // Note: geometry.x/y is the CENTER of the shape
-    const left = x - width / 2;
-    const right = x + width / 2;
-    const top = y - height / 2;
-    const bottom = y + height / 2;
-
-    switch (hole.anchor) {
-      case "top-left":
-        bx = left;
-        by = top;
-        break;
-      case "top-center":
-        bx = x;
-        by = top;
-        break;
-      case "top-right":
-        bx = right;
-        by = top;
-        break;
-      case "center-left":
-        bx = left;
-        by = y;
-        break;
-      case "center":
-        bx = x;
-        by = y;
-        break;
-      case "center-right":
-        bx = right;
-        by = y;
-        break;
-      case "bottom-left":
-        bx = left;
-        by = bottom;
-        break;
-      case "bottom-center":
-        bx = x;
-        by = bottom;
-        break;
-      case "bottom-right":
-        bx = right;
-        by = bottom;
-        break;
-    }
-
-    return {
-      x: bx + (hole.offsetX || 0),
-      y: by + (hole.offsetY || 0),
-    };
-  } else if (hole.x !== undefined && hole.y !== undefined) {
-    // Legacy / Direct coordinates (Normalized relative to Dieline Geometry)
-    // Formula: absolute = normalized * width + (center - width/2)
-    // This handles padding correctly.
-    const { x, width, y, height } = geometry;
-    return {
-      x: hole.x * width + (x - width / 2) + (hole.offsetX || 0),
-      y: hole.y * height + (y - height / 2) + (hole.offsetY || 0),
-    };
-  }
-  return { x: 0, y: 0 };
+export type FeatureOperation = "add" | "subtract";
+export type FeatureShape = "rect" | "circle";
+
+export interface DielineFeature {
+  id: string;
+  groupId?: string;
+  operation: FeatureOperation;
+  shape: FeatureShape;
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+  radius?: number;
+  rotation?: number;
+  placement?: "edge" | "internal";
+  color?: string;
+  strokeDash?: number[];
+  skipCut?: boolean;
 }
 
 export interface GeometryOptions {
@@ -102,7 +27,7 @@ export interface GeometryOptions {
   radius: number;
   x: number;
   y: number;
-  holes: Array<HoleData>;
+  features: Array<DielineFeature>;
   pathData?: string;
   canvasWidth?: number;
   canvasHeight?: number;
@@ -113,6 +38,24 @@ export interface MaskGeometryOptions extends GeometryOptions {
   canvasHeight: number;
 }
 
+/**
+ * Resolves the absolute position of a feature based on normalized coordinates.
+ */
+export function resolveFeaturePosition(
+  feature: DielineFeature,
+  geometry: { x: number; y: number; width: number; height: number },
+): { x: number; y: number } {
+  const { x, y, width, height } = geometry;
+  // geometry.x/y is the Center.
+  const left = x - width / 2;
+  const top = y - height / 2;
+
+  return {
+    x: left + feature.x * width,
+    y: top + feature.y * height,
+  };
+}
+
 /**
  * Initializes paper.js project if not already initialized.
  */
@@ -153,9 +96,6 @@ function createBaseShape(options: GeometryOptions): paper.PathItem {
     path.pathData = pathData;
     // Align center
     path.position = center;
-    // Scale to match width/height if needed?
-    // For now, assume pathData is correct size, but we might want to support resizing.
-    // If width/height are provided and different from bounds, we could scale.
     if (
       width > 0 &&
       height > 0 &&
@@ -166,7 +106,6 @@ function createBaseShape(options: GeometryOptions): paper.PathItem {
     }
     return path;
   } else {
-    // Fallback
     return new paper.Path.Rectangle({
       point: [x - width / 2, y - height / 2],
       size: [Math.max(0, width), Math.max(0, height)],
@@ -175,225 +114,148 @@ function createBaseShape(options: GeometryOptions): paper.PathItem {
 }
 
 /**
- * Creates an offset version of the base shape.
- * For Rect/Circle, we can just adjust params.
- * For Custom shapes, we need a true offset algorithm (Paper.js doesn't have a robust one built-in for all cases,
- * but we can simulate it or use a simple scaling if offset is small, OR rely on a library like Clipper.js.
- * However, since we want to avoid heavy deps, let's try a simple approach:
- * If it's a simple shape, we re-create it.
- * If it's custom, we unfortunately have to scale it for now as a poor-man's offset,
- * UNLESS we implement a stroke expansion.
- *
- * Stroke Expansion Trick:
- * 1. Create path
- * 2. Set strokeWidth = offset * 2
- * 3. Convert stroke to path (paper.js has path.expand())
- * 4. Union original + expanded (for positive offset) or Subtract (for negative).
+ * Creates a Paper.js Item for a single feature.
  */
-function createOffsetShape(
-  options: GeometryOptions,
-  offset: number,
+function createFeatureItem(
+  feature: DielineFeature,
+  center: paper.Point,
 ): paper.PathItem {
-  const { shape, width, height, radius, x, y, pathData } = options;
-  const center = new paper.Point(x, y);
-
-  if (shape === "rect" || shape === "circle" || shape === "ellipse") {
-    // For standard shapes, we can just adjust the dimensions
-    const offsetOptions = {
-      ...options,
-      width: Math.max(0, width + offset * 2),
-      height: Math.max(0, height + offset * 2),
-      radius: radius === 0 ? 0 : Math.max(0, radius + offset),
-    };
-    return createBaseShape(offsetOptions);
-  } else if (shape === "custom" && pathData) {
-    const original = createBaseShape(options);
-    if (offset === 0) return original;
-
-    // Use Stroke Expansion for Offset
-    // Create a copy for stroking
-    const stroker = original.clone() as paper.Path;
-    stroker.strokeColor = new paper.Color("black");
-    stroker.strokeWidth = Math.abs(offset) * 2;
-    // Round join usually looks better for offsets
-    stroker.strokeJoin = "round";
-    stroker.strokeCap = "round";
-
-    // Expand stroke to path
-    // @ts-ignore - paper.js types might be missing expand depending on version, but it exists in recent versions
-    // If expand is not available, we might fallback to scaling.
-    // Assuming modern paper.js
-    let expanded: paper.Item;
-    try {
-      // @ts-ignore
-      expanded = stroker.expand({ stroke: true, fill: false, insert: false });
-    } catch (e) {
-      // Fallback if expand fails or not present
-      stroker.remove();
-      // Fallback to scaling (imperfect)
-      const scaleX =
-        (original.bounds.width + offset * 2) / original.bounds.width;
-      const scaleY =
-        (original.bounds.height + offset * 2) / original.bounds.height;
-      original.scale(scaleX, scaleY);
-      return original;
-    }
-
-    stroker.remove();
-
-    // The expanded stroke is a "ring".
-    // For positive offset: Union(Original, Ring)
-    // For negative offset: Subtract(Original, Ring) ? No, that makes a hole.
-    // For negative offset: We want the "inner" boundary of the ring.
-
-    // Actually, expand() returns a Group or Path.
-    // If it's a closed path, the ring has an outer and inner boundary.
-
-    let result: paper.PathItem;
-
-    if (offset > 0) {
-      // @ts-ignore
-      result = original.unite(expanded);
-    } else {
-      // For negative offset (shrink), we want the original MINUS the stroke?
-      // No, the stroke is centered on the line.
-      // So the inner edge of the stroke is at -offset.
-      // We want the area INSIDE the inner edge.
-      // That is Original SUBTRACT the Ring?
-      // Yes, if we subtract the ring, we lose the border area.
-      // @ts-ignore
-      result = original.subtract(expanded);
-    }
-
-    // Cleanup
-    original.remove();
-    expanded.remove();
+  let item: paper.PathItem;
+
+  if (feature.shape === "rect") {
+    const w = feature.width || 10;
+    const h = feature.height || 10;
+    const r = feature.radius || 0;
+    item = new paper.Path.Rectangle({
+      point: [center.x - w / 2, center.y - h / 2],
+      size: [w, h],
+      radius: r,
+    });
+  } else {
+    // Circle
+    const r = feature.radius || 5;
+    item = new paper.Path.Circle({
+      center: center,
+      radius: r,
+    });
+  }
 
-    return result;
+  if (feature.rotation) {
+    item.rotate(feature.rotation, center);
   }
 
-  return createBaseShape(options);
+  return item;
 }
 
 /**
- * Internal helper to generate the Dieline Shape (Paper Item).
- * Caller is responsible for cleanup.
+ * Internal helper to generate the Perimeter Shape (Base + Edge Features).
  */
-function getDielineShape(options: GeometryOptions): paper.PathItem {
+function getPerimeterShape(options: GeometryOptions): paper.PathItem {
   // 1. Create Base Shape
   let mainShape = createBaseShape(options);
 
-  const { holes } = options;
-
-  if (holes && holes.length > 0) {
-    let lugsPath: paper.PathItem | null = null;
-    let cutsPath: paper.PathItem | null = null;
-
-    holes.forEach((hole) => {
-      const center = new paper.Point(hole.x!, hole.y!);
-
-      // Create Lug (Outer Radius)
-      const lug =
-        hole.shape === "square"
-          ? new paper.Path.Rectangle({
-              point: [
-                center.x - hole.outerRadius,
-                center.y - hole.outerRadius,
-              ],
-              size: [hole.outerRadius * 2, hole.outerRadius * 2],
-            })
-          : new paper.Path.Circle({
-              center: center,
-              radius: hole.outerRadius,
-            });
-
-      // REMOVED: Intersects check. We want to process all holes defined in config.
-      // If a hole is completely outside, it might form an island, but that's better than missing it.
-      // Users can remove the hole if they don't want it.
-
-      // Create Cut (Inner Radius)
-      const cut =
-        hole.shape === "square"
-          ? new paper.Path.Rectangle({
-              point: [
-                center.x - hole.innerRadius,
-                center.y - hole.innerRadius,
-              ],
-              size: [hole.innerRadius * 2, hole.innerRadius * 2],
-            })
-          : new paper.Path.Circle({
-              center: center,
-              radius: hole.innerRadius,
-            });
-
-      // Union Lugs
-      if (!lugsPath) {
-        lugsPath = lug;
+  const { features } = options;
+
+  if (features && features.length > 0) {
+    // Filter for Edge Features (Default or explicit 'edge')
+    const edgeFeatures = features.filter(
+      (f) => !f.placement || f.placement === "edge",
+    );
+
+    const adds: paper.PathItem[] = [];
+    const subtracts: paper.PathItem[] = [];
+
+    edgeFeatures.forEach((f) => {
+      const pos = resolveFeaturePosition(f, options);
+      const center = new paper.Point(pos.x, pos.y);
+      const item = createFeatureItem(f, center);
+      
+      if (f.operation === "add") {
+        adds.push(item);
       } else {
+        subtracts.push(item);
+      }
+    });
+
+    // 2. Process Additions (Union)
+    if (adds.length > 0) {
+      for (const item of adds) {
         try {
-          const temp = lugsPath.unite(lug);
-          lugsPath.remove();
-          lug.remove();
-          lugsPath = temp;
+          const temp = mainShape.unite(item);
+          mainShape.remove();
+          item.remove();
+          mainShape = temp;
         } catch (e) {
-          console.error("Geometry: Failed to unite lug", e);
-          // Keep previous lugsPath, ignore this one to prevent crash
-          lug.remove();
+          console.error("Geometry: Failed to unite feature", e);
+          item.remove();
         }
       }
+    }
 
-      // Union Cuts
-      if (!cutsPath) {
-        cutsPath = cut;
-      } else {
+    // 3. Process Subtractions (Difference)
+    if (subtracts.length > 0) {
+      for (const item of subtracts) {
         try {
-          const temp = cutsPath.unite(cut);
-          cutsPath.remove();
-          cut.remove();
-          cutsPath = temp;
+          const temp = mainShape.subtract(item);
+          mainShape.remove();
+          item.remove();
+          mainShape = temp;
         } catch (e) {
-          console.error("Geometry: Failed to unite cut", e);
-          cut.remove();
+          console.error("Geometry: Failed to subtract feature", e);
+          item.remove();
         }
       }
-    });
-
-    // 2. Add Lugs to Main Shape (Union) - Additive Fusion
-    if (lugsPath) {
-      try {
-        const temp = mainShape.unite(lugsPath);
-        mainShape.remove();
-        // @ts-ignore
-        lugsPath.remove();
-        mainShape = temp;
-      } catch (e) {
-        console.error("Geometry: Failed to unite lugsPath to mainShape", e);
-      }
     }
+  }
+
+  return mainShape;
+}
+
+/**
+ * Applies Internal/Surface features to a shape.
+ */
+function applySurfaceFeatures(
+  shape: paper.PathItem,
+  features: DielineFeature[],
+  options: GeometryOptions,
+): paper.PathItem {
+  const internalFeatures = features.filter((f) => f.placement === "internal");
+  
+  if (internalFeatures.length === 0) return shape;
+
+  let result = shape;
+  
+  // Internal features are usually subtractive (holes)
+  // But we support 'add' too (islands? maybe just unite)
+  
+  for (const f of internalFeatures) {
+    const pos = resolveFeaturePosition(f, options);
+    const center = new paper.Point(pos.x, pos.y);
+    const item = createFeatureItem(f, center);
 
-    // 3. Subtract Cuts from Main Shape (Difference)
-    if (cutsPath) {
-      try {
-        const temp = mainShape.subtract(cutsPath);
-        mainShape.remove();
-        // @ts-ignore
-        cutsPath.remove();
-        mainShape = temp;
-      } catch (e) {
-        console.error(
-          "Geometry: Failed to subtract cutsPath from mainShape",
-          e,
-        );
+    try {
+      if (f.operation === "add") {
+         const temp = result.unite(item);
+         result.remove();
+         item.remove();
+         result = temp;
+      } else {
+         const temp = result.subtract(item);
+         result.remove();
+         item.remove();
+         result = temp;
       }
+    } catch (e) {
+      console.error("Geometry: Failed to apply surface feature", e);
+      item.remove();
     }
   }
-
-  return mainShape;
+  
+  return result;
 }
 
 /**
  * Generates the path data for the Dieline (Product Shape).
- * Logic: (BaseShape UNION IntersectingLugs) SUBTRACT Cuts
  */
 export function generateDielinePath(options: GeometryOptions): string {
   const paperWidth = options.canvasWidth || options.width * 2 || 2000;
@@ -401,10 +263,11 @@ export function generateDielinePath(options: GeometryOptions): string {
   ensurePaper(paperWidth, paperHeight);
   paper.project.activeLayer.removeChildren();
 
-  const mainShape = getDielineShape(options);
+  const perimeter = getPerimeterShape(options);
+  const finalShape = applySurfaceFeatures(perimeter, options.features, options);
 
-  const pathData = mainShape.pathData;
-  mainShape.remove();
+  const pathData = finalShape.pathData;
+  finalShape.remove();
 
   return pathData;
 }
@@ -419,16 +282,14 @@ export function generateMaskPath(options: MaskGeometryOptions): string {
 
   const { canvasWidth, canvasHeight } = options;
 
-  // 1. Canvas Background
   const maskRect = new paper.Path.Rectangle({
     point: [0, 0],
     size: [canvasWidth, canvasHeight],
   });
 
-  // 2. Re-create Product Shape
-  const mainShape = getDielineShape(options);
+  const perimeter = getPerimeterShape(options);
+  const mainShape = applySurfaceFeatures(perimeter, options.features, options);
 
-  // 3. Subtract Product from Mask
   const finalMask = maskRect.subtract(mainShape);
 
   maskRect.remove();
@@ -441,92 +302,27 @@ export function generateMaskPath(options: MaskGeometryOptions): string {
 }
 
 /**
- * Generates the path data for the Bleed Zone (Area between Original and Offset).
+ * Generates the path data for the Bleed Zone.
  */
 export function generateBleedZonePath(
-  options: GeometryOptions,
+  originalOptions: GeometryOptions,
+  offsetOptions: GeometryOptions,
   offset: number,
 ): string {
-  // Ensure canvas is large enough
-  const paperWidth = options.canvasWidth || options.width * 2 || 2000;
-  const paperHeight = options.canvasHeight || options.height * 2 || 2000;
+  const paperWidth =
+    originalOptions.canvasWidth || originalOptions.width * 2 || 2000;
+  const paperHeight =
+    originalOptions.canvasHeight || originalOptions.height * 2 || 2000;
   ensurePaper(paperWidth, paperHeight);
   paper.project.activeLayer.removeChildren();
 
-  // 1. Original Shape
-  const shapeOriginal = getDielineShape(options);
-
-  // 2. Offset Shape
-  // We use createOffsetShape for more accurate offset (especially for custom shapes)
-  // But we still need to respect holes if they exist.
-  // getDielineShape handles holes.
-  // The issue is: do holes shrink/expand with bleed?
-  // Usually, bleed is only for the outer cut. Holes are internal cuts.
-  // Internal cuts usually also have bleed if they are die-cut, but maybe different direction?
-  // For simplicity, let's assume we offset the FINAL shape (including holes).
-
-  // Actually, getDielineShape calls createBaseShape.
-  // Let's modify generateBleedZonePath to use createOffsetShape logic if possible,
-  // OR just perform offset on the final shape result.
-
-  // The previous logic was: create base shape with adjusted width/height/radius.
-  // This works for Rect/Circle.
-  // For Custom, we need createOffsetShape.
-
-  let shapeOffset: paper.PathItem;
-
-  if (options.shape === "custom") {
-    // For custom shape, we offset the base shape first, then apply holes?
-    // Or offset the final result?
-    // Bleed is usually "outside" the cut line.
-    // If we have a donut, bleed is outside the outer circle AND inside the inner circle?
-    // Or just outside the outer?
-    // Let's assume bleed expands the solid area.
-
-    // So we take the final shape (Original) and expand it.
-    // We can use the same Stroke Expansion trick on the final shape.
-
-    // Since shapeOriginal is already the final shape (Base - Holes),
-    // we can try to offset it directly.
-
-    const stroker = shapeOriginal.clone() as paper.Path;
-    stroker.strokeColor = new paper.Color("black");
-    stroker.strokeWidth = Math.abs(offset) * 2;
-    stroker.strokeJoin = "round";
-    stroker.strokeCap = "round";
-
-    let expanded: paper.Item;
-    try {
-      // @ts-ignore
-      expanded = stroker.expand({ stroke: true, fill: false, insert: false });
-    } catch (e) {
-      // Fallback
-      stroker.remove();
-      shapeOffset = shapeOriginal.clone();
-      // scaling fallback...
-      return shapeOffset.pathData; // Fail gracefully
-    }
-    stroker.remove();
-
-    if (offset > 0) {
-      // @ts-ignore
-      shapeOffset = shapeOriginal.unite(expanded);
-    } else {
-      // @ts-ignore
-      shapeOffset = shapeOriginal.subtract(expanded);
-    }
-    expanded.remove();
-  } else {
-    // Legacy logic for standard shapes (still valid and fast)
-    // Adjust dimensions for offset
-    const offsetOptions: GeometryOptions = {
-      ...options,
-      width: Math.max(0, options.width + offset * 2),
-      height: Math.max(0, options.height + offset * 2),
-      radius: options.radius === 0 ? 0 : Math.max(0, options.radius + offset),
-    };
-    shapeOffset = getDielineShape(offsetOptions);
-  }
+  // 1. Generate Original Shape
+  const pOriginal = getPerimeterShape(originalOptions);
+  const shapeOriginal = applySurfaceFeatures(pOriginal, originalOptions.features, originalOptions);
+
+  // 2. Generate Offset Shape
+  const pOffset = getPerimeterShape(offsetOptions);
+  const shapeOffset = applySurfaceFeatures(pOffset, offsetOptions.features, offsetOptions);
 
   // 3. Calculate Difference
   let bleedZone: paper.PathItem;
@@ -538,7 +334,6 @@ export function generateBleedZonePath(
 
   const pathData = bleedZone.pathData;
 
-  // Cleanup
   shapeOriginal.remove();
   shapeOffset.remove();
   bleedZone.remove();
@@ -547,8 +342,8 @@ export function generateBleedZonePath(
 }
 
 /**
- * Finds the nearest point on the Dieline geometry for a given target point.
- * Used for constraining hole movement.
+ * Finds the nearest point on the Dieline geometry (Base Shape ONLY) for a given target point.
+ * Used for constraining feature movement.
  */
 export function getNearestPointOnDieline(
   point: { x: number; y: number },
@@ -557,6 +352,8 @@ export function getNearestPointOnDieline(
   ensurePaper(options.width * 2, options.height * 2);
   paper.project.activeLayer.removeChildren();
 
+  // We constrain to the BASE shape, not including other features,
+  // because usually you want to snap to the main edge.
   const shape = createBaseShape(options);
 
   const p = new paper.Point(point.x, point.y);