paper-roll-pallet

Roll/pallet palletization: a framework-free packing solver and data model, plus an optional React SVG visualization at the ./react subpath. Import just the main entry to get pure logic with zero dependencies, or add paper-roll-pallet/react when you also want the component (React is a peer dependency only for that subpath).

Model

A roll stands on its circular end, so its contribution to a pallet's stack height equals its width (mm), and its footprint is its diameter. A pallet is a single vertical tower of rolls (no side-by-side stacking). A tower's height must not exceed maxStackHeightMm (equipment internal height minus pallet height).

Main entry (paper-roll-pallet)

No dependencies, no React.

• types — PalletizationRowInput, PalletizationConfig, PlannedRoll, PlannedPallet, PalletizationPlan.
• rollMath — wound-roll length/weight math, kg ↔ roll-count conversion.
• rollColors — deterministic colour-per-roll-type palette.
• solver — solvePalletization(rows, config): FFD + maximal-pattern enumeration bin-packing into pallets/trucks.
• palletPatterns — groups solved pallets into { count, rolls } patterns for display/editing, plus pure edit operations (changeCount, addRollToPattern, removeRollFromPattern, …).
• planDocument — serializable plan document with schema versioning, staleness detection, and approval tracking.
• rollAssignment — matches the PHYSICAL rolls of a pallet being packed (roll number + measured width) to the planned slots: assignRollsToPattern, stackOrder.

import { solvePalletization, groupIntoPatterns, buildPlanFromPatterns } from 'paper-roll-pallet';

const plan = solvePalletization(rows, config);
const patterns = plan.feasible ? groupIntoPatterns(plan) : [];

paper-roll-pallet/react

<PackagingPlanGraphic> — draws a plan as SVG (roll towers with cylindrical shading, a pallet glyph, engineering-style dimension lines, a legend, optional drag-and-drop editing). No MUI, no CSS framework.

import { PackagingPlanGraphic, type RollType } from 'paper-roll-pallet/react';

<PackagingPlanGraphic
  patterns={patterns}
  maxStackHeightMm={config.maxStackHeightMm}
  palletHeightMm={palletHeightMm}
  palletLongerSideMm={palletLongerSideMm}
  rollTypes={rollTypes}
/>

Pass editing plus the onCountDelta/onAddPattern/onDeletePattern/ onDropRoll/onRemoveRoll callbacks to enable interactive editing.

Packaging mode — physical roll numbers on a pallet

While a pallet is actually being built, the operator enters the roll number and measured width of every roll that goes on it. Pass those per pallet as assignmentsByPattern and the graphic shows how far the pallet has got: rolls that have a physical roll are drawn solid with their roll number written across them, and every planned roll still missing is faded (50 % by default). With nothing entered yet the whole tower is faded.

<PackagingPlanGraphic
  patterns={[{ id: 'pallet-1', diameterMm: 600, count: 1, rolls: sixRollsOf395 }]}
  maxStackHeightMm={2550}
  rollTypes={rollTypes}
  patternTitles={{ 'pallet-1': 'Pallet 1' }}
  assignmentsByPattern={{
    'pallet-1': [
      { rollNumber: '1234', widthMm: 395 },
      { rollNumber: '1235', widthMm: 395 },
    ],
  }}
/>

Roll numbers belong to one physical pallet, so in packaging mode pass one pattern per pallet with count: 1 and key the assignments by its id — a pattern with count: 6 is six different pallets. Passing the prop at all switches the graphic into packaging mode, so a pattern with no entry is drawn entirely faded.

Slots are filled bottom-up, and a roll takes the lowest free slot whose planned width matches its own — so a mixed 900 + 900 + 390 pallet stays correct no matter what order the rolls are entered in. A roll whose width matches no free slot still takes the lowest free one but is outlined in the error colour and shows its measured width; rolls left over once the pallet is full are listed under the card as extras. Use widthToleranceMm to allow a measurement margin, unassignedOpacity to change the fade, and formatAssignedCount / labels.extraRolls to localize the texts.

Roll numbers are drawn on a translucent plate in a monospace font, and the type size shrinks to fit both the segment height and the roll width, so long codes stay legible whatever the host theme is. Override with theme.rollNumberBackground, theme.rollNumberColor and rollNumberFontFamily.

The same matching is available without React:

import { assignRollsToPattern } from 'paper-roll-pallet';

const { slots, extras, assignedCount, complete } = assignRollsToPattern(
  pattern.rolls,
  [{ rollNumber: '1234', widthMm: 395 }],
);

Customizing strings, number formatting, and colours

<PackagingPlanGraphic
  {...props}
  labels={{ legend: 'Rullatyypit', addPattern: 'Uusi lavotus' }}
  formatValue={(mm) => `${mm.toLocaleString('fi-FI')} mm`}
  theme={{ hoverBorderColor: '#0057b8' }}
/>

Development

npm run build       # tsup -> dist/{index,react}.{js,cjs,d.ts}
npm test             # vitest run — pure-logic tests only

No component tests are included for PackagingPlanGraphic — UI is verified manually via a dev server in the consuming app.