@lucablockltd/ultimate-packaging 1.0.0

package/dist/AGENTS_README.md

@@ -0,0 +1,472 @@
+# ultimate-packaging — AI Agent Reference
+
+> React library for packaging dieline rendering and auto-layout on paper sheets.
+> This document is optimized for AI agents to understand and use the library correctly.
+
+## Quick Start
+
+```bash
+npm install PinitS/ultimate-packaging
+```
+
+Requires `react >= 18.0.0` and `react-dom >= 18.0.0`.
+
+---
+
+## 1. Show a Dieline (Simplest Usage)
+
+Use `DIE_LINE_LAYOUT` — one component for ALL models. No switch-case needed.
+
+```tsx
+import { DIE_LINE_LAYOUT, modelList } from "ultimate-packaging";
+import type { DieLineLayoutRef } from "ultimate-packaging";
+
+const ref = useRef<DieLineLayoutRef>(null);
+
+// Get default attributes for any model
+const model = modelList.find(m => m.id === "BECF-1010A")!;
+
+<DIE_LINE_LAYOUT
+  ref={ref}
+  modelId="BECF-1010A"
+  attributes={model.attributes}
+  unit="mm"
+  mode="DIE_LINE"
+  isShowDimensions={true}
+/>
+```
+
+### DIE_LINE_LAYOUT Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `modelId` | `string` | YES | — | One of: `"BECF-1010A"`, `"BECF-1030A"`, `"BECF-1040A"`, `"BECF-11D01"` |
+| `attributes` | `object` | YES | — | Box dimensions (see Model Attributes below) |
+| `unit` | `"mm" \| "cm" \| "in"` | no | `"mm"` | Display unit for dimension labels |
+| `mode` | `ModelMode` | no | `"DIE_LINE"` | `"DIE_LINE"` = interactive canvas, `"AUTO_LAYOUT"` = raw SVG |
+| `isShowDimensions` | `boolean` | no | `false` | Show dimension annotation lines |
+
+### DIE_LINE_LAYOUT Ref Methods
+
+```tsx
+const ref = useRef<DieLineLayoutRef>(null);
+
+// Get current attributes
+ref.current.getAttributes(); // → { length: 60, width: 25, ... }
+
+// Export as PNG image
+const blob = await ref.current.exportImage({ isShowDimension: true, originalSize: true });
+
+// Export dimensions as PDF
+const pdf = await ref.current.exportDimension();
+```
+
+---
+
+## 2. Auto-Layout (Pack Dielines on Paper)
+
+Use `AUTO_LAYOUT` to automatically arrange dieline pieces on paper sheets.
+
+```tsx
+import { AUTO_LAYOUT, calculateAutoLayout } from "ultimate-packaging";
+import type { AutoLayoutRef, AutoLayoutConfig, AutoLayoutResult } from "ultimate-packaging";
+
+const ref = useRef<AutoLayoutRef>(null);
+const [result, setResult] = useState<AutoLayoutResult | null>(null);
+
+const config: AutoLayoutConfig = {
+  papers: [
+    { paperId: "1", paperName: "20x28\"", paperWidth: 508, paperHeight: 711.2 },
+    { paperId: "2", paperName: "25x36\"", paperWidth: 635, paperHeight: 914.4 },
+  ],
+  model: {
+    modelId: "BECF-1010A",
+    attributes: { length: 60, width: 25, height: 100, glueArea: 15, dustFlap: 15, tuckFlap: 15 },
+  },
+  quantity: 1000,
+  layoutDistance: 3,     // mm gap between pieces (offset contour)
+  spacing: 5,           // mm margin on sides
+  griper: 10,           // mm machine gripper zone
+  colorbarHeight: 5,    // mm colorbar strip height
+  isShowColorbar: true,
+};
+
+<AUTO_LAYOUT ref={ref} config={config} onResult={setResult} />
+```
+
+### AUTO_LAYOUT Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `AutoLayoutConfig \| null` | YES | Layout configuration (null = no render) |
+| `onResult` | `(result: AutoLayoutResult \| null) => void` | no | Called when layout is calculated |
+| `onModifiedPapers` | `(papers: AutoLayoutPaperResult[]) => void` | no | Called when user modifies layout manually |
+
+### AUTO_LAYOUT Ref Methods
+
+```tsx
+// Get calculation result
+ref.current.getResult(); // → AutoLayoutResult
+
+// Export layout image (PNG) for specific paper
+const png = await ref.current.exportImage(0); // paper index 0
+
+// Export layout as PDF
+const pdf = await ref.current.exportPdf(0);
+
+// Get packed result with dieline + layout image files
+const packed = await ref.current.getPackedResult(0);
+// → { ...paperResult, quantity, dielineFile: File, layoutFile: File }
+```
+
+### Programmatic Calculation (No UI)
+
+```tsx
+import { calculateAutoLayout } from "ultimate-packaging";
+
+const result = calculateAutoLayout(config);
+// → AutoLayoutResult { papers, quantity, totalProduced, totalSheets, remainingNeeded, recommendedPaperId }
+```
+
+---
+
+## 3. Available Models & Attributes
+
+### Get All Models
+
+```tsx
+import { modelList } from "ultimate-packaging";
+
+modelList.forEach(model => {
+  console.log(model.id);         // "BECF-1010A"
+  console.log(model.name);       // "Tuck End Box BECF-1010A"
+  console.log(model.dimension);  // ["DIE_LINE"]
+  console.log(model.attributes); // { length: 60, width: 25, ... }
+});
+```
+
+### Model Attribute Schemas
+
+#### Tuck End Boxes (BECF-1010A, BECF-1030A, BECF-1040A)
+
+```typescript
+interface TuckEndBoxAttributes {
+  length: number;    // box length (mm)
+  width: number;     // box width (mm)
+  height: number;    // box height (mm)
+  glueArea: number;  // glue flap width (mm)
+  dustFlap: number;  // dust flap extension (mm)
+  tuckFlap: number;  // tuck flap height (mm)
+}
+```
+
+| Model | length | width | height | glueArea | dustFlap | tuckFlap |
+|-------|--------|-------|--------|----------|----------|----------|
+| BECF-1010A | 60 | 25 | 100 | 15 | 15 | 15 |
+| BECF-1030A | 105 | 50 | 155 | 15 | 25 | 14 |
+| BECF-1040A | 56 | 56 | 150 | 15 | 30 | 14 |
+
+#### Standard Box (BECF-11D01)
+
+```typescript
+interface StandardBoxAttributes {
+  length: number;     // box length (mm)
+  width: number;      // box width (mm)
+  height: number;     // box height (mm)
+  flapHeight: number; // top/bottom flap height (mm)
+  glueArea: number;   // glue flap width (mm)
+}
+```
+
+| Model | length | width | height | flapHeight | glueArea |
+|-------|--------|-------|--------|------------|----------|
+| BECF-11D01 | 100 | 50 | 150 | 50 | 13 |
+
+### Default Attribute Constants
+
+```tsx
+import {
+  BECF_1010A_DEFAULT_ATTRIBUTES,
+  BECF_1030A_DEFAULT_ATTRIBUTES,
+  BECF_1040A_DEFAULT_ATTRIBUTES,
+  BECF_11D01_DEFAULT_ATTRIBUTES,
+} from "ultimate-packaging";
+```
+
+---
+
+## 4. Type Reference
+
+### AutoLayoutConfig
+
+```typescript
+interface AutoLayoutConfig {
+  papers: AutoLayoutPaper[];        // paper sizes to try
+  model: AutoLayoutModel;           // { modelId, attributes }
+  quantity: number;                  // total pieces needed
+  layoutDistance: number;            // mm between piece cut-lines
+  spacing: number;                  // mm margin on paper sides
+  griper: number;                   // mm machine gripper zone
+  colorbarHeight: number;           // mm colorbar strip
+  isShowColorbar: boolean;          // show colorbar on layout
+}
+
+interface AutoLayoutPaper {
+  paperId: string;
+  paperName: string;
+  paperWidth: number;   // mm
+  paperHeight: number;  // mm
+}
+```
+
+### AutoLayoutResult
+
+```typescript
+interface AutoLayoutResult {
+  papers: AutoLayoutPaperResult[];  // results per paper size
+  quantity: number;
+  totalProduced: number;
+  totalSheets: number;
+  remainingNeeded: number;
+  recommendedPaperId: string | null; // most efficient paper
+}
+
+interface AutoLayoutPaperResult {
+  paperId: string;
+  paperName: string;
+  paperWidth: number;
+  paperHeight: number;
+  producedPerSheet: number;         // pieces per sheet
+  totalSheets: number;
+  totalProduced: number;
+  excessCount: number;              // overproduction
+  wastePercent: number;             // paper waste %
+  independentSheets: number;        // sheets if using only this paper
+  independentTotalArea: number;     // total paper area (mm²)
+  placements: AutoLayoutPlacement[];
+  gripperSide: GripperSide;         // "top" | "bottom" | "left" | "right"
+}
+
+interface AutoLayoutPlacement {
+  x: number;        // mm from paper left
+  y: number;        // mm from paper top
+  rotation: number; // 0 | 90 | 180 | 270
+}
+```
+
+### AutoLayoutPackedResult
+
+```typescript
+interface AutoLayoutPackedResult extends AutoLayoutPaperResult {
+  quantity: number;
+  dielineFile: File;   // dieline pattern image
+  layoutFile: File;    // layout arrangement image
+}
+```
+
+### ModelMode
+
+```typescript
+type ModelMode = "DIE_LINE" | "3D" | "AUTO_LAYOUT";
+```
+
+---
+
+## 5. Theme Configuration
+
+```tsx
+import { configurePackaging } from "ultimate-packaging";
+
+// Call ONCE at app startup, BEFORE rendering any components
+configurePackaging({
+  modelTheme: {
+    colorBackground: "#FAFAFA",
+    colorDieLine: "#FF0000",     // cut lines
+    colorFoldLine: "#00FF00",    // crease lines
+  },
+  autoLayoutTheme: {
+    colorBackground: "#F5F5F5",
+    colorPaperFill: "#FFFFFF",
+    colorPaperStroke: "#999999",
+    colorGriper: "#228B22",
+    colorSpacing: "#f54278",
+    colorDistanceLine: "#0088FF", // blue offset contour
+    colorDieLine: "#FF0000",
+    colorFoldLine: "#00FF00",
+    colorLabel: "#333333",
+  },
+});
+```
+
+---
+
+## 6. Complete Imports Cheat Sheet
+
+```tsx
+// Components
+import {
+  DIE_LINE_LAYOUT,           // Recommended: auto-switches by modelId
+  AUTO_LAYOUT,               // Auto-layout packing on paper
+  MODEL_BECF_1010A,          // Direct model components (if needed)
+  MODEL_BECF_1030A,
+  MODEL_BECF_1040A,
+  MODEL_BECF_11D01,
+  Colorbar,                  // Sub-components for custom rendering
+  Gripper,
+} from "ultimate-packaging";
+
+// Types
+import type {
+  DieLineLayoutRef,
+  DieLineLayoutProps,
+  AutoLayoutRef,
+  AutoLayoutProps,
+  AutoLayoutConfig,
+  AutoLayoutResult,
+  AutoLayoutPaperResult,
+  AutoLayoutPackedResult,
+  AutoLayoutPlacement,
+  AutoLayoutPaper,
+  AutoLayoutModel,
+  TuckEndBoxAttributes,
+  StandardBoxAttributes,
+  ModelMode,
+  PackagingModel,
+  GripperSide,
+  ModifyPlacement,
+  ModelThemeConfig,
+  AutoLayoutThemeConfig,
+  UltimatePackagingConfig,
+} from "ultimate-packaging";
+
+// Data & Constants
+import {
+  modelList,                        // PackagingModel[] — all models with defaults
+  BECF_1010A_DEFAULT_ATTRIBUTES,
+  BECF_1030A_DEFAULT_ATTRIBUTES,
+  BECF_1040A_DEFAULT_ATTRIBUTES,
+  BECF_11D01_DEFAULT_ATTRIBUTES,
+  MODEL_THEME_CONFIG,
+  AUTO_LAYOUT_THEME_CONFIG,
+} from "ultimate-packaging";
+
+// Functions
+import {
+  configurePackaging,               // Set global theme
+  calculateAutoLayout,              // Compute layout without UI
+} from "ultimate-packaging";
+```
+
+---
+
+## 7. Common Patterns
+
+### Pattern A: Display a Dieline with Controls
+
+```tsx
+import { DIE_LINE_LAYOUT, modelList } from "ultimate-packaging";
+import type { DieLineLayoutRef } from "ultimate-packaging";
+
+function DielineEditor() {
+  const ref = useRef<DieLineLayoutRef>(null);
+  const [modelId, setModelId] = useState("BECF-1010A");
+  const [attrs, setAttrs] = useState(modelList[0].attributes);
+
+  const handleModelChange = (id: string) => {
+    setModelId(id);
+    setAttrs(modelList.find(m => m.id === id)!.attributes);
+  };
+
+  return (
+    <>
+      <select value={modelId} onChange={e => handleModelChange(e.target.value)}>
+        {modelList.map(m => <option key={m.id} value={m.id}>{m.name}</option>)}
+      </select>
+      <DIE_LINE_LAYOUT ref={ref} modelId={modelId} attributes={attrs} />
+    </>
+  );
+}
+```
+
+### Pattern B: Auto-Layout with Export
+
+```tsx
+import { AUTO_LAYOUT } from "ultimate-packaging";
+import type { AutoLayoutRef, AutoLayoutConfig, AutoLayoutResult } from "ultimate-packaging";
+
+function LayoutPlanner() {
+  const ref = useRef<AutoLayoutRef>(null);
+  const [result, setResult] = useState<AutoLayoutResult | null>(null);
+
+  const config: AutoLayoutConfig = {
+    papers: [{ paperId: "1", paperName: "20x28\"", paperWidth: 508, paperHeight: 711.2 }],
+    model: { modelId: "BECF-1010A", attributes: { length: 60, width: 25, height: 100, glueArea: 15, dustFlap: 15, tuckFlap: 15 } },
+    quantity: 500,
+    layoutDistance: 3,
+    spacing: 5,
+    griper: 10,
+    colorbarHeight: 5,
+    isShowColorbar: true,
+  };
+
+  const handleExport = async () => {
+    const packed = await ref.current!.getPackedResult(0);
+    // packed.dielineFile → File (dieline image)
+    // packed.layoutFile  → File (layout image)
+    // packed.producedPerSheet → number
+  };
+
+  return (
+    <>
+      <AUTO_LAYOUT ref={ref} config={config} onResult={setResult} />
+      {result && <p>Best: {result.recommendedPaperId} — {result.papers[0].producedPerSheet} pcs/sheet</p>}
+      <button onClick={handleExport}>Export</button>
+    </>
+  );
+}
+```
+
+### Pattern C: Headless Calculation (No React)
+
+```tsx
+import { calculateAutoLayout } from "ultimate-packaging";
+
+const result = calculateAutoLayout({
+  papers: [
+    { paperId: "A", paperName: "20x28\"", paperWidth: 508, paperHeight: 711.2 },
+    { paperId: "B", paperName: "25x36\"", paperWidth: 635, paperHeight: 914.4 },
+  ],
+  model: { modelId: "BECF-1030A", attributes: { length: 105, width: 50, height: 155, glueArea: 15, dustFlap: 25, tuckFlap: 14 } },
+  quantity: 1000,
+  layoutDistance: 3,
+  spacing: 5,
+  griper: 10,
+  colorbarHeight: 5,
+  isShowColorbar: true,
+});
+
+console.log(result.recommendedPaperId); // "B"
+result.papers.forEach(p => {
+  console.log(`${p.paperName}: ${p.producedPerSheet} pcs/sheet, ${p.wastePercent}% waste`);
+});
+```
+
+---
+
+## 8. Important Rules
+
+1. **Units are always millimeters** — all attributes, paper sizes, layout distances are in mm internally. The `unit` prop only affects display labels.
+
+2. **`configurePackaging()` must be called before rendering** — call once at app startup to set theme colors.
+
+3. **`modelList` contains all models with defaults** — use it to populate dropdowns and get default attributes. Never hardcode model lists.
+
+4. **`DIE_LINE_LAYOUT` is the recommended component** — it handles model switching internally. Only use `MODEL_*` components directly if you need model-specific type safety.
+
+5. **Paper dimensions for auto-layout are in mm** — convert inches to mm: `inches * 25.4`. Common sizes: 20x28" = 508x711.2mm, 25x36" = 635x914.4mm.
+
+6. **`layoutDistance` is the gap between cut-lines** — internally divided by 2 to create the offset contour on each side. Set to 0 for pieces touching.
+
+7. **`ref` methods are async for exports** — `exportImage()`, `exportDimension()`, `exportPdf()`, `getPackedResult()` all return `Promise<Blob>` or `Promise<File>`.
+
+8. **`rotation` in placements is degrees** — always one of: 0, 90, 180, 270.