@pooder/kit 4.1.0 → 4.3.0

package/src/constraints.ts

@@ -1,17 +1,35 @@
-import { DielineFeature } from "./geometry";
+import { DielineFeature, getNearestPointOnDieline, getLowestPointOnDieline } from "./geometry";
 
 export interface ConstraintContext {
   dielineWidth: number;
   dielineHeight: number;
+  // Context may need access to geometry functions or the geometry itself
+  // For now, getNearestPointOnDieline creates its own paper scope, but ideally we pass a simplified geometry representation
+  geometry?: any; 
+}
+
+export interface ConstraintFeature extends DielineFeature {
+  constraints?: Array<{
+    type: string;
+    params?: any;
+    validateOnly?: boolean;
+  }>;
 }
 
 export type ConstraintHandler = (
   x: number,
   y: number,
-  feature: DielineFeature,
-  context: ConstraintContext
+  feature: ConstraintFeature,
+  context: ConstraintContext,
+  params?: any
 ) => { x: number; y: number };
 
+export interface ConstraintConfig {
+  type: string;
+  params?: any;
+  validateOnly?: boolean;
+}
+
 export class ConstraintRegistry {
   private static handlers = new Map<string, ConstraintHandler>();
 
@@ -22,40 +40,118 @@ export class ConstraintRegistry {
   static apply(
     x: number,
     y: number,
-    feature: DielineFeature,
-    context: ConstraintContext
+    feature: ConstraintFeature,
+    context: ConstraintContext,
+    constraints?: ConstraintConfig[] // Optional override, defaults to feature.constraints
   ): { x: number; y: number } {
-    if (!feature.constraints || !feature.constraints.type) {
+    const list = constraints || feature.constraints;
+    if (!list || list.length === 0) {
       return { x, y };
     }
 
-    const handler = this.handlers.get(feature.constraints.type);
-    if (handler) {
-      return handler(x, y, feature, context);
+    let currentX = x;
+    let currentY = y;
+
+    for (const constraint of list) {
+      const handler = this.handlers.get(constraint.type);
+      if (handler) {
+        const result = handler(currentX, currentY, feature, context, constraint.params || {});
+        currentX = result.x;
+        currentY = result.y;
+      }
     }
 
-    return { x, y };
+    return { x: currentX, y: currentY };
   }
 }
 
 // --- Built-in Strategies ---
 
 /**
- * Edge Constraint Strategy
- * Snaps the feature to the nearest allowed edge.
- * Params:
- * - allowedEdges: ('top' | 'bottom' | 'left' | 'right')[] (default: all)
- * - confine: boolean (default: false) - if true, keeps feature within edge length
- * - offset: number (default: 0) - physical offset from edge (positive = inwards usually, but here 0 is edge)
- *   For simplicity, let's say offset is additive to the edge position.
- *   Top: 0 + offset
- *   Bottom: 1 - offset
- *   Left: 0 + offset
- *   Right: 1 - offset
+ * Path Constraint Strategy (formerly placement='edge')
+ * Snaps the feature to the nearest point on the Dieline Path.
+ */
+const pathConstraint: ConstraintHandler = (x, y, feature, context, params) => {
+    // We need to denormalize, find nearest, then normalize back
+    // This is expensive but accurate.
+    const { dielineWidth, dielineHeight, geometry } = context;
+    if (!geometry) return { x, y }; // Cannot snap without geometry
+    
+    // Geometry is centered at (cx, cy)
+    // x, y are normalized (0-1) relative to bounding box
+    const minX = geometry.x - geometry.width / 2;
+    const minY = geometry.y - geometry.height / 2;
+    
+    const absX = minX + x * geometry.width;
+    const absY = minY + y * geometry.height;
+    
+    // Use geometry helper
+    // Note: getNearestPointOnDieline creates a fresh paper scope each time.
+    // Optimization: geometry object passed in context could be a reusable paper path?
+    // For now, keep it simple as per existing logic.
+    const nearest = getNearestPointOnDieline(
+      { x: absX, y: absY },
+      geometry
+    );
+
+    let finalX = nearest.x;
+    let finalY = nearest.y;
+
+    // Only allow vertical offset if explicit offset limits are provided
+    // Otherwise, we snap strictly to the path (offset = 0)
+    const hasOffsetParams = params.minOffset !== undefined || params.maxOffset !== undefined;
+
+    if (hasOffsetParams && nearest.normal) {
+        // Project the cursor vector onto the normal vector
+        // This ensures the feature stays on the "normal line" of the nearest path point
+        const dx = absX - nearest.x;
+        const dy = absY - nearest.y;
+        
+        const nx = nearest.normal.x;
+        const ny = nearest.normal.y;
+        
+        // Dot product to get scalar projection
+        const dist = dx * nx + dy * ny;
+        
+        // Limit the offset
+        // geometry.width is in pixels, dielineWidth is in physical units (e.g. mm)
+        // We assume dielineWidth corresponds to geometry.width
+        const scale = dielineWidth > 0 ? geometry.width / dielineWidth : 1;
+        
+        // If one is provided but the other is not, default the other to 0.
+        // If neither is provided (shouldn't happen due to hasOffsetParams check), default to 0.
+        const rawMin = params.minOffset !== undefined ? params.minOffset : 0;
+        const rawMax = params.maxOffset !== undefined ? params.maxOffset : 0;
+        
+        // However, if we want to allow one-sided infinity, user must explicitly provide Infinity?
+        // Wait, user requirement: "If only one is passed, the other defaults to 0."
+        // This implies:
+        // { minOffset: -5 } -> maxOffset = 0 (range: -5 to 0)
+        // { maxOffset: 5 } -> minOffset = 0 (range: 0 to 5)
+        // { minOffset: -5, maxOffset: 5 } -> (range: -5 to 5)
+        
+        const minOffset = rawMin * scale;
+        const maxOffset = rawMax * scale;
+        
+        const clampedDist = Math.max(minOffset, Math.min(dist, maxOffset));
+
+        finalX = nearest.x + nx * clampedDist;
+        finalY = nearest.y + ny * clampedDist;
+    }
+    
+    // Re-normalize
+    const nx = geometry.width > 0 ? (finalX - minX) / geometry.width : 0.5;
+    const ny = geometry.height > 0 ? (finalY - minY) / geometry.height : 0.5;
+    
+    return { x: nx, y: ny };
+};
+
+/**
+ * Edge Constraint Strategy (Box Edge)
+ * Snaps the feature to the nearest allowed edge of the BOUNDING BOX.
  */
-const edgeConstraint: ConstraintHandler = (x, y, feature, context) => {
+const edgeConstraint: ConstraintHandler = (x, y, feature, context, params) => {
   const { dielineWidth, dielineHeight } = context;
-  const params = feature.constraints?.params || {};
   const allowedEdges = params.allowedEdges || [
     "top",
     "bottom",
@@ -130,12 +226,9 @@ const edgeConstraint: ConstraintHandler = (x, y, feature, context) => {
 /**
  * Internal Constraint Strategy
  * Keeps the feature strictly inside the dieline bounds with optional margin.
- * Params:
- * - margin: number (default: 0) - physical margin
  */
-const internalConstraint: ConstraintHandler = (x, y, feature, context) => {
+const internalConstraint: ConstraintHandler = (x, y, feature, context, params) => {
   const { dielineWidth, dielineHeight } = context;
-  const params = feature.constraints?.params || {};
   const margin = params.margin || 0;
   const fw = feature.width || 0;
   const fh = feature.height || 0;
@@ -153,6 +246,77 @@ const internalConstraint: ConstraintHandler = (x, y, feature, context) => {
   return { x: clampedX, y: clampedY };
 };
 
+/**
+ * Bottom Tangent Strategy (stand protrusion)
+ * Forces a feature to be tangent to the dieline bottom edge from outside (below).
+ */
+const tangentBottomConstraint: ConstraintHandler = (x, y, feature, context, params) => {
+  const { dielineWidth, dielineHeight } = context;
+  const gap = params.gap || 0;
+  const confineX = params.confineX !== false;
+
+  const extentY =
+    feature.shape === "circle"
+      ? feature.radius || 0
+      : (feature.height || 0) / 2;
+  const newY = 1 + (extentY + gap) / dielineHeight;
+
+  let newX = x;
+  if (confineX) {
+    const extentX =
+      feature.shape === "circle"
+        ? feature.radius || 0
+        : (feature.width || 0) / 2;
+    const minX = extentX / dielineWidth;
+    const maxX = 1 - extentX / dielineWidth;
+    newX = minX > maxX ? 0.5 : Math.max(minX, Math.min(newX, maxX));
+  }
+
+  return { x: newX, y: newY };
+};
+
+/**
+ * Lowest Tangent Strategy (Lowest Point Lock)
+ * Finds the lowest point of the Dieline geometry and locks the feature's Y to that level.
+ * Allows horizontal movement (X).
+ */
+const lowestTangentConstraint: ConstraintHandler = (x, y, feature, context, params) => {
+  const { dielineWidth, dielineHeight, geometry } = context;
+  if (!geometry) return { x, y };
+
+  const lowest = getLowestPointOnDieline(geometry);
+  
+  // Calculate normalized Y of the lowest point
+  const minY = geometry.y - geometry.height / 2;
+  const normY = (lowest.y - minY) / geometry.height;
+  
+  const gap = params.gap || 0;
+  const confineX = params.confineX !== false;
+
+  const extentY =
+    feature.shape === "circle"
+      ? feature.radius || 0
+      : (feature.height || 0) / 2;
+      
+  const newY = normY + (extentY + gap) / dielineHeight;
+
+  let newX = x;
+  if (confineX) {
+    const extentX =
+      feature.shape === "circle"
+        ? feature.radius || 0
+        : (feature.width || 0) / 2;
+    const minX = extentX / dielineWidth;
+    const maxX = 1 - extentX / dielineWidth;
+    newX = minX > maxX ? 0.5 : Math.max(minX, Math.min(newX, maxX));
+  }
+  
+  return { x: newX, y: newY };
+};
+
 // Register built-ins
+ConstraintRegistry.register("path", pathConstraint);
 ConstraintRegistry.register("edge", edgeConstraint);
 ConstraintRegistry.register("internal", internalConstraint);
+ConstraintRegistry.register("tangent-bottom", tangentBottomConstraint);
+ConstraintRegistry.register("lowest-tangent", lowestTangentConstraint);

package/src/coordinate.ts

@@ -1,106 +1,106 @@
-export interface Point {
-  x: number;
-  y: number;
-}
-
-export interface Size {
-  width: number;
-  height: number;
-}
-
-export type Unit = "px" | "mm" | "cm" | "in";
-
-export interface Layout {
-  scale: number;
-  offsetX: number;
-  offsetY: number;
-  width: number;
-  height: number;
-}
-
-export class Coordinate {
-  /**
-   * Calculate layout to fit content within container while preserving aspect ratio.
-   */
-  static calculateLayout(
-    container: Size,
-    content: Size,
-    padding: number = 0,
-  ): Layout {
-    const availableWidth = Math.max(0, container.width - padding * 2);
-    const availableHeight = Math.max(0, container.height - padding * 2);
-
-    if (content.width === 0 || content.height === 0) {
-      return { scale: 1, offsetX: 0, offsetY: 0, width: 0, height: 0 };
-    }
-
-    const scaleX = availableWidth / content.width;
-    const scaleY = availableHeight / content.height;
-    const scale = Math.min(scaleX, scaleY);
-
-    const width = content.width * scale;
-    const height = content.height * scale;
-
-    const offsetX = (container.width - width) / 2;
-    const offsetY = (container.height - height) / 2;
-
-    return { scale, offsetX, offsetY, width, height };
-  }
-
-  /**
-   * Convert an absolute value to a normalized value (0-1).
-   * @param value Absolute value (e.g., pixels)
-   * @param total Total dimension size (e.g., canvas width)
-   */
-  static toNormalized(value: number, total: number): number {
-    return total === 0 ? 0 : value / total;
-  }
-
-  /**
-   * Convert a normalized value (0-1) to an absolute value.
-   * @param normalized Normalized value (0-1)
-   * @param total Total dimension size (e.g., canvas width)
-   */
-  static toAbsolute(normalized: number, total: number): number {
-    return normalized * total;
-  }
-
-  /**
-   * Normalize a point's coordinates.
-   */
-  static normalizePoint(point: Point, size: Size): Point {
-    return {
-      x: this.toNormalized(point.x, size.width),
-      y: this.toNormalized(point.y, size.height),
-    };
-  }
-
-  /**
-   * Denormalize a point's coordinates to absolute pixels.
-   */
-  static denormalizePoint(point: Point, size: Size): Point {
-    return {
-      x: this.toAbsolute(point.x, size.width),
-      y: this.toAbsolute(point.y, size.height),
-    };
-  }
-
-  static convertUnit(value: number, from: Unit, to: Unit): number {
-    if (from === to) return value;
-    
-    // Base unit: mm
-    const toMM: Record<Unit, number> = {
-      px: 0.264583, // 1px = 0.264583mm (96 DPI)
-      mm: 1,
-      cm: 10,
-      in: 25.4
-    };
-
-    const mmValue = value * (from === 'px' ? toMM.px : toMM[from] || 1);
-    
-    if (to === 'px') {
-        return mmValue / toMM.px;
-    }
-    return mmValue / (toMM[to] || 1);
-  }
-}
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export type Unit = "px" | "mm" | "cm" | "in";
+
+export interface Layout {
+  scale: number;
+  offsetX: number;
+  offsetY: number;
+  width: number;
+  height: number;
+}
+
+export class Coordinate {
+  /**
+   * Calculate layout to fit content within container while preserving aspect ratio.
+   */
+  static calculateLayout(
+    container: Size,
+    content: Size,
+    padding: number = 0,
+  ): Layout {
+    const availableWidth = Math.max(0, container.width - padding * 2);
+    const availableHeight = Math.max(0, container.height - padding * 2);
+
+    if (content.width === 0 || content.height === 0) {
+      return { scale: 1, offsetX: 0, offsetY: 0, width: 0, height: 0 };
+    }
+
+    const scaleX = availableWidth / content.width;
+    const scaleY = availableHeight / content.height;
+    const scale = Math.min(scaleX, scaleY);
+
+    const width = content.width * scale;
+    const height = content.height * scale;
+
+    const offsetX = (container.width - width) / 2;
+    const offsetY = (container.height - height) / 2;
+
+    return { scale, offsetX, offsetY, width, height };
+  }
+
+  /**
+   * Convert an absolute value to a normalized value (0-1).
+   * @param value Absolute value (e.g., pixels)
+   * @param total Total dimension size (e.g., canvas width)
+   */
+  static toNormalized(value: number, total: number): number {
+    return total === 0 ? 0 : value / total;
+  }
+
+  /**
+   * Convert a normalized value (0-1) to an absolute value.
+   * @param normalized Normalized value (0-1)
+   * @param total Total dimension size (e.g., canvas width)
+   */
+  static toAbsolute(normalized: number, total: number): number {
+    return normalized * total;
+  }
+
+  /**
+   * Normalize a point's coordinates.
+   */
+  static normalizePoint(point: Point, size: Size): Point {
+    return {
+      x: this.toNormalized(point.x, size.width),
+      y: this.toNormalized(point.y, size.height),
+    };
+  }
+
+  /**
+   * Denormalize a point's coordinates to absolute pixels.
+   */
+  static denormalizePoint(point: Point, size: Size): Point {
+    return {
+      x: this.toAbsolute(point.x, size.width),
+      y: this.toAbsolute(point.y, size.height),
+    };
+  }
+
+  static convertUnit(value: number, from: Unit, to: Unit): number {
+    if (from === to) return value;
+    
+    // Base unit: mm
+    const toMM: Record<Unit, number> = {
+      px: 0.264583, // 1px = 0.264583mm (96 DPI)
+      mm: 1,
+      cm: 10,
+      in: 25.4
+    };
+
+    const mmValue = value * (from === 'px' ? toMM.px : toMM[from] || 1);
+    
+    if (to === 'px') {
+        return mmValue / toMM.px;
+    }
+    return mmValue / (toMM[to] || 1);
+  }
+}