@mark1russell7/packing 0.1.6 → 0.1.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/packing",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Rectangle packing: shelf, guillotine and skyline strategies, push cascades and measures of a layout.",
   "keywords": [
     "rectangle-packing",
@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@mark1russell7/cue": "^1.0.2",
-    "@mark1russell7/layout-contract": "github:mark1russell7/layout-contract#69933a61b0270c5915b82ab563d24908ade708af&path:packages/layout-contract",
+    "@mark1russell7/layout-contract": "github:mark1russell7/layout-contract#710ec519027dbc122d111cc5e76a1c18877f4237&path:packages/layout-contract",
     "@types/node": "^26.6.4",
     "tsdown": "^0.23.1",
     "typescript": "^7.0.2",

package/src/check.ts

@@ -28,8 +28,11 @@ function overlap(a: Box, b: Box, tolerance: number): boolean {
  * - `no-overlap`: each pair of items with their margins, and each pair of an item and an obstacle, that overlap by more than `tolerance.overlap`.
  * - `in-container`: each item with its margin that goes out of a fixed side by more than `tolerance.overlap`. The inset of
  *   the container makes each fixed side smaller (decision 3 of `docs/PACKER.md`).
- * - `locked-kept`: each locked item that moved by more than `RECORD_EPS`, or that has no position.
- * - `complete`: each item with no position that is not in the overflow.
+ * - `locked-kept`: each locked item that moved by more than `RECORD_EPS`, or that has no placement.
+ * - `complete`: each item with no placement that is not in the overflow. A locked item breaks `locked-kept` in its place.
+ *
+ * A locked item with no placement stays at its input position for `no-overlap` and `in-container`. A locked item with no
+ * `x` or no `y` in the input is not locked for these rules.
  *
  * The rules read a shape of the container, of an obstacle or of an item as its bounding box (decision 5). The bounding box
  * of an item shape is relative to the position of the item. The result has no tolerance in it.
@@ -43,14 +46,18 @@ export function checkHard(input: PackInput, output: PackOutput, tolerance: Pick<
 
   const boxes: Box[] = [];
   for (const item of input.items) {
-    const p = placements.get(item.id);
+    const lockedAt = item.locked === true && item.x !== undefined && item.y !== undefined ? { x: item.x, y: item.y } : undefined;
+    let p: Pick<PackOutput["placements"][number], "x" | "y" | "turn"> | undefined = placements.get(item.id);
     if (p === undefined) {
-      if (item.locked === true && item.x !== undefined && item.y !== undefined) breaks["locked-kept"] += 1;
-      if (!overflow.has(item.id)) breaks.complete += 1;
-      continue;
-    }
-    if (item.locked === true && item.x !== undefined && item.y !== undefined) {
-      if (Math.abs(p.x - item.x) > RECORD_EPS || Math.abs(p.y - item.y) > RECORD_EPS) breaks["locked-kept"] += 1;
+      if (lockedAt === undefined) {
+        if (!overflow.has(item.id)) breaks.complete += 1;
+        continue;
+      }
+      // A locked item with no placement breaks locked-kept, and it stays at its input position for the other rules
+      breaks["locked-kept"] += 1;
+      p = lockedAt;
+    } else if (lockedAt !== undefined) {
+      if (Math.abs(p.x - lockedAt.x) > RECORD_EPS || Math.abs(p.y - lockedAt.y) > RECORD_EPS) breaks["locked-kept"] += 1;
     }
     const placed: Item = p.turn === 90 ? turnItem(item) : item;
     const m = marginOf(placed);

package/src/contract.ts

@@ -72,6 +72,8 @@ export interface Item {
   margin?: number | Margin;
   /** The ports. The packer keeps them, and turns them with the item. */
   ports?: Port[];
+  /** The free data of the item. The packer does not read it, and the turn and the converters keep it. */
+  data?: Readonly<Record<string, unknown>>;
 }
 
 /** The input of a packing: a `layout-input/1` file without `edges`, with `items` for `boxes`. */

package/src/layout-input.ts

@@ -11,6 +11,8 @@ export interface Edge {
   target: string;
   sourcePort?: string;
   targetPort?: string;
+  /** The free data of the edge. The packer does not read it. */
+  data?: Readonly<Record<string, unknown>>;
 }
 
 /** The parameters of a generator: a name and a string or a number for each parameter. */

package/src/measures.ts

@@ -23,6 +23,20 @@ export interface MeasureSpec {
   min: number;
   /** The highest value. The value `Infinity` tells that the measure has no upper limit. */
   max: number;
+  /**
+   * The floor is the best value of a guard measure. The floor rule of `docs/PROMOTION.md` of `highways` reads it. Each
+   * guard of the packer has the floor 0. A measure without a floor has no floor rule.
+   */
+  floor?: number;
+  /**
+   * The tolerance is the absolute tolerance at the floor. A candidate within the tolerance ties with a default at the floor.
+   *
+   * - `pack.order.inversions` and `pack.overflow` have the tolerance 0. Thus each new inversion and each new unplaced item is a loss.
+   * - `pack.aspectError` has 0.01, approximately 1% of the aspect. An exact tiling gives the default an error of 0.
+   * - `pack.stability.mean` has 0.005 container widths, and `pack.stability.q95` has 0.01. The default often moves no item.
+   * - `pack.stability.moved` has 0.02: 2% of the items that stay. On a small change, the default often moves no item.
+   */
+  tol?: number;
 }
 
 /** The measures of one layout, by id. `measure` gives them. The values are not rounded. */
@@ -56,29 +70,33 @@ export interface MeasureOptions {
   rowTolerance?: number;
 }
 
-const spec = (id: MeasureId, family: MeasureFamily, unit: string, direction: Direction, min: number, max: number): MeasureSpec => ({
-  id,
-  family,
-  unit,
-  direction,
-  min,
-  max,
-});
+const spec = (
+  id: MeasureId,
+  family: MeasureFamily,
+  unit: string,
+  direction: Direction,
+  min: number,
+  max: number,
+  guard?: { floor: number; tol: number },
+): MeasureSpec => ({ id, family, unit, direction, min, max, ...guard });
 
-/** The facts of each measure, by id. `docs/MEASURES.md` gives the full definitions. */
+/**
+ * The facts of each measure, by id. `docs/MEASURES.md` gives the full definitions. This record is the source of the floor
+ * and the tolerance of each guard of the packer.
+ */
 export const MEASURE_SPECS: Readonly<Record<MeasureId, MeasureSpec>> = Object.freeze({
   "pack.area": spec("pack.area", "density", "square units", "lower", 0, Infinity),
   "pack.fill": spec("pack.fill", "density", "share", "higher", 0, 1),
   "pack.whitespace": spec("pack.whitespace", "density", "share", "lower", 0, 1),
   "pack.aspect": spec("pack.aspect", "aspect", "ratio", "lower", 1, Infinity),
-  "pack.aspectError": spec("pack.aspectError", "aspect", "natural log", "lower", 0, Infinity),
-  "pack.order.inversions": spec("pack.order.inversions", "order", "share", "lower", 0, 1),
+  "pack.aspectError": spec("pack.aspectError", "aspect", "natural log", "lower", 0, Infinity, { floor: 0, tol: 0.01 }),
+  "pack.order.inversions": spec("pack.order.inversions", "order", "share", "lower", 0, 1, { floor: 0, tol: 0 }),
   "pack.order.breaks": spec("pack.order.breaks", "order", "count", "lower", 0, Infinity),
   "pack.raggedness": spec("pack.raggedness", "raggedness", "share", "lower", 0, 1),
-  "pack.overflow": spec("pack.overflow", "overflow", "count", "lower", 0, Infinity),
-  "pack.stability.moved": spec("pack.stability.moved", "stability", "share", "lower", 0, 1),
-  "pack.stability.mean": spec("pack.stability.mean", "stability", "container widths", "lower", 0, Infinity),
-  "pack.stability.q95": spec("pack.stability.q95", "stability", "container widths", "lower", 0, Infinity),
+  "pack.overflow": spec("pack.overflow", "overflow", "count", "lower", 0, Infinity, { floor: 0, tol: 0 }),
+  "pack.stability.moved": spec("pack.stability.moved", "stability", "share", "lower", 0, 1, { floor: 0, tol: 0.02 }),
+  "pack.stability.mean": spec("pack.stability.mean", "stability", "container widths", "lower", 0, Infinity, { floor: 0, tol: 0.005 }),
+  "pack.stability.q95": spec("pack.stability.q95", "stability", "container widths", "lower", 0, Infinity, { floor: 0, tol: 0.01 }),
   "pack.deterministic": spec("pack.deterministic", "determinism", "boolean", "higher", 0, 1),
   "pack.search.widths": spec("pack.search.widths", "speed", "count", "lower", 0, Infinity),
   "pack.search.ms": spec("pack.search.ms", "speed", "milliseconds", "lower", 0, Infinity),