@mark1russell7/packing 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @mark1russell7/packing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@mark1russell7/packing?color=2346c4)](https://www.npmjs.com/package/@mark1russell7/packing) [![CI](https://github.com/mark1russell7/packing/actions/workflows/ci.yml/badge.svg)](https://github.com/mark1russell7/packing/actions/workflows/ci.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-2346c4)](https://github.com/mark1russell7/packing/blob/main/packages/packing/LICENSE)
+
+Rectangle packing for layouts: a guillotine row packer and a skyline packer that place rectangles in an outer rectangle.
+
+```sh
+npm i @mark1russell7/packing
+```
+
+```ts
+import { pack, Rect } from "@mark1russell7/packing";
+
+const rects = [[30, 10], [20, 20], [10, 5]].map(([w, h]) => {
+  const r = new Rect<string>();
+  r.size.set(w, h);
+  return r;
+});
+const outer = pack(rects);
+outer.size; // the size of the layout
+rects[0].position; // the place of the first rectangle
+```
+
+Without fixed sizes, the outer rectangle grows until all rectangles fit. With `fixedWidth`, the width stays. With `fixedSize`, a rectangle that does not fit stays unpacked.
+
+## Strategies
+
+`pack` sets the width of the outer rectangle, and then packs with a strategy:
+
+```ts
+pack(rects, outer, { strategy: "skyline", sortOrder: "area-desc" });
+```
+
+- `packRows` (the default): a guillotine row packing. It fills the space under the short rectangles of each row.
+- `packSkyline`: each rectangle goes to the lowest place where it fits. It packs around a `locked` rectangle.
+- `packShelf`: it fills rows left to right in the sort order, and goes around each `locked` rectangle. With the sort order `input`, the rows read in your order.
+
+Both functions also work alone, in an outer rectangle with a width that you set. They do not change the width.
+
+A `locked` rectangle keeps its position. `packSkyline` and `packShelf` put the other rectangles around it. `packRows` only keeps its position.
+
+The sort orders are `height-desc` (the default), `height-asc`, `width-desc`, `area-desc` and `input`. `SORT_ORDERS` lists them, and `compareRects` gives the comparator of one.
+
+The order `input` keeps the order of your array. Use it for a ranked list. `packRows` then fills no gaps, so the rows read in your order: left to right, and top to bottom. `packSkyline` places the rectangles in your order, but a later rectangle can go higher than an earlier one. For a ranked list with `locked` rectangles, use `packShelf`.
+
+## Pushes and measurements
+
+`pushCascade` moves the rectangles that a placed rectangle overlaps, and the rectangles that those overlap in turn:
+
+```ts
+const moved = pushCascade(dropped, cards, { gap: 8 });
+```
+
+- Each shove takes the axis of the smaller overlap, away from the pusher. The cascade goes outward, and a rectangle does not go past 0.
+- The placed rectangle and each `locked` rectangle stay. `maxShoves` limits the work.
+
+`packingMetrics` measures a packing: the hull and its aspect, the rows and the raggedness of the right side. It also gives the part of the hull that the rectangles cover (`utilization`), and the widest rectangle against the median.
+
+```ts
+const { utilization, raggedness, rows } = packingMetrics(Rect.packed(rects));
+```
+
+## More
+
+- [The repository](https://github.com/mark1russell7/packing): the source, the tests and the roadmap.
+- This package was `@mark1russell7/render-pack` before 0.1.0. `render-pack` re-exports this package for one more minor, and then it is deprecated.
+
+The package is ESM, has TypeScript declarations, and works in Node.js 22.12 or later and in browsers. The license is MIT.

package/build/index.d.ts

@@ -0,0 +1,209 @@
+/** A mutable two-dimensional vector. */
+export declare class Vector {
+  #private;
+  constructor(x?: number, y?: number);
+  /** The first component: a width or a left position. */
+  get x(): number;
+  set x(v: number);
+  /** The second component: a height or a top position. */
+  get y(): number;
+  set y(v: number);
+  /** This method sets both components. */
+  set(x: number, y: number): void;
+  /** This method copies the components of another vector. */
+  setTo(v: Vector): void;
+  /** This method gives a new vector: the sum of this vector and another. */
+  add(other: Vector): Vector;
+  /** This method gives the product of the components: the area of a size. */
+  area(): number;
+  /** This method gives a new vector with the same components. */
+  clone(): Vector;
+  /** This method gives a new vector with each component between the components of `min` and `max`. */
+  clamp(min: Vector, max: Vector): Vector;
+  /** This function gives a vector with the same value in both components. */
+  static of(scalar: number): Vector;
+  /** This function gives the smallest value of each component, or a zero vector for an empty list. */
+  static min(vectors: Vector[]): Vector;
+  /** This function gives the largest value of each component, or a zero vector for an empty list. */
+  static max(vectors: Vector[]): Vector;
+  /** This getter gives a new infinite vector each time. A shared value is not safe, because a vector is mutable. */
+  static get Infinity(): Vector;
+}
+/** A rectangle of the packer. `id` identifies the item that it measures. The packer sets `position` and `wasPacked`. */
+export declare class Rect<T = unknown> {
+  #private;
+  /** The identity of the item that the rectangle measures. */
+  id?: T;
+  /** The packer sets this field to `true` when it places the rectangle. */
+  wasPacked: boolean;
+  /** For an outer rectangle: the packer keeps its width. */
+  fixedWidth: boolean;
+  /** For an outer rectangle: the packer keeps its width and its height, and it skips a rectangle that does not fit. */
+  fixedSize: boolean;
+  /**
+   * The packer keeps the position of a locked rectangle. `packSkyline` packs the other rectangles around it.
+   * `packRows` only keeps its position, and other rectangles can overlap it.
+   */
+  locked: boolean;
+  /** The top left corner. */
+  get position(): Vector;
+  /** The width and the height. */
+  get size(): Vector;
+  /** This method gives the right edge. */
+  right(): number;
+  /** This method gives the bottom edge. */
+  bottom(): number;
+  /** This method moves the left edge to the right by an amount, and the right edge stays. */
+  shrinkLeft(amount: number): this;
+  /** This method moves the rectangle by an offset. */
+  translateBy(offset: Vector): this;
+  /** This method gives the area of the size. */
+  area(): number;
+  /** This function gives the rectangles that the packer placed. */
+  static packed<U>(rects: Rect<U>[]): Rect<U>[];
+  /** This function gives the rectangles that the packer did not place. */
+  static unpacked<U>(rects: Rect<U>[]): Rect<U>[];
+  /** This function marks each rectangle as not placed. A locked rectangle stays placed. */
+  static resetPacked<U>(rects: Rect<U>[]): void;
+  /** This function gives the largest right edge, or 0 for an empty list. */
+  static maxRight<U>(rects: Rect<U>[]): number;
+  /** This function gives the largest bottom edge, or 0 for an empty list. */
+  static maxBottom<U>(rects: Rect<U>[]): number;
+}
+/**
+ * An order of the rectangles before the packing. The order changes the layout much. `input` keeps the order of
+ * the array of the caller: the row packing then fills no gaps, so its rows read in that order.
+ */
+type SortOrder = "height-desc" | "height-asc" | "width-desc" | "area-desc" | "input";
+/** This constant lists each sort order. The first one is the default. */
+export declare const SORT_ORDERS: readonly SortOrder[];
+/** This function gives the comparator of a sort order. The sort is stable, so `input` keeps the order. */
+export declare function compareRects(order: SortOrder): <T>(a: Rect<T>, b: Rect<T>) => number;
+/** The options of `pack` and `packRows` */
+interface PackOptions {
+  /** The order of the rectangles before the packing. The default is `height-desc`. */
+  sortOrder?: SortOrder;
+}
+/** The options of `pack` */
+interface PackLayoutOptions extends PackOptions {
+  /**
+   * The packing: `rows` (the default), `skyline` or `shelf`. `skyline` and `shelf` pack around locked rectangles.
+   * Use `shelf` with the sort order `input` to keep the order of the array around locked rectangles.
+   */
+  strategy?: "rows" | "skyline" | "shelf";
+}
+/**
+ * This function packs rectangles into an outer rectangle of a given width with a guillotine row packing. It does
+ * not change the width. Without `fixedSize`, the height grows until all rectangles fit. A `locked` rectangle keeps
+ * its position, but the rows do not go around it. `pack` sets the width first and then uses this function.
+ */
+export declare function packRows<T>(rects: Rect<T>[], outer: Rect<T>, options?: PackOptions): Rect<T>;
+/**
+ * This function packs rectangles into an outer rectangle with a guillotine row packing. It sets the position
+ * of each rectangle and the size of the outer rectangle, and it gives the outer rectangle.
+ *
+ * - Without fixed sizes, the outer rectangle starts with a width of 1.5 times the square root of the total area.
+ *   This width is not less than the width of the widest rectangle. The height grows until all rectangles fit.
+ * - With `fixedWidth`, the width stays. A rectangle wider than that width goes on its own row and overflows.
+ * - With `fixedSize`, a rectangle that does not fit is not packed: its `wasPacked` stays `false`.
+ * - `options.strategy` selects `packRows` (the default), `packSkyline` or `packShelf` after the width is set.
+ */
+export declare function pack<T>(rects: Rect<T>[], outer?: Rect<T>, options?: PackLayoutOptions): Rect<T>;
+/**
+ * This function finds the lowest window of width `rw` on a skyline. For each `x` in `[0, width - rw]`, the height
+ * of the window is the largest value of `skyline[x, x + rw)`. The first `x` with the smallest height wins. A
+ * monotonic deque makes the search O(width) for one rectangle.
+ */
+export declare function lowestWindow(skyline: ArrayLike<number>, width: number, rw: number): {
+  x: number;
+  y: number;
+};
+/**
+ * This function packs rectangles into an outer rectangle with a skyline. It puts each rectangle in the lowest place
+ * where it fits, and it does not change the width of the outer rectangle.
+ *
+ * - A `locked` rectangle keeps its position. The skyline starts at its bottom edge across its width, thus the other
+ *   rectangles go under it. The space above it stays empty, because a skyline has no holes.
+ * - The skyline has a cell for each whole unit of the width. A rectangle that needs more cells than the outer
+ *   rectangle has goes under all other rectangles, at the left edge.
+ * - Without `fixedSize`, the height of the outer rectangle grows to the content. With `fixedSize`, a rectangle that
+ *   does not fit is not packed: its `wasPacked` stays `false`.
+ * - The default sort order is `height-desc`. The order of the array of the caller stays.
+ */
+export declare function packSkyline<T>(rects: Rect<T>[], outer: Rect<T>, options?: {
+  sortOrder?: SortOrder;
+}): Rect<T>;
+/** The options of `packShelf` */
+interface ShelfOptions {
+  /** The order of the rectangles before the packing. The default is `height-desc`. */
+  sortOrder?: SortOrder;
+}
+/**
+ * This function packs rectangles into shelves: rows that it fills left to right in the sort order, and does not fill
+ * again. It goes around each `locked` rectangle. It sets the position of each rectangle and gives the outer rectangle.
+ *
+ * - With the sort order `input`, the rows read in the order of the array: left to right, and top to bottom.
+ * - With `height-desc` (the default), it is the classic Next-Fit Decreasing Height packing.
+ * - A rectangle goes to the first x in the row where it crosses no locked rectangle. If no such x is in the width,
+ *   a new row starts under the current row.
+ * - A rectangle wider than the outer rectangle goes on its own row, at the left edge, and overflows.
+ * - It does not change the width. Without `fixedSize`, the height grows to the content. With `fixedSize`, a
+ *   rectangle that does not fit is not packed: its `wasPacked` stays `false`.
+ */
+export declare function packShelf<T>(rects: Rect<T>[], outer: Rect<T>, options?: ShelfOptions): Rect<T>;
+/** The options of `pushCascade`. */
+interface PushOptions {
+  /** The space between a shoved rectangle and the rectangle that shoves it. The default is 8. */
+  gap?: number;
+  /** The most shoves. The default is eight for each rectangle. The cascade stops at this limit. */
+  maxShoves?: number;
+}
+/**
+ * This function moves each rectangle that a placed rectangle overlaps, and the rectangles that those overlap in turn.
+ * A shove takes the axis of the smaller overlap, away from the pusher. A shoved rectangle keeps the direction of its first
+ * shove when it shoves the next one, so the cascade goes outward. The placed rectangle and each locked rectangle stay.
+ * The function moves the rectangles in place and gives the rectangles that moved.
+ *
+ * @example
+ * ```ts
+ * const moved = pushCascade(dropped, cards, { gap: 8 });
+ * ```
+ */
+export declare function pushCascade<T>(placed: Rect<T>, rects: readonly Rect<T>[], options?: PushOptions): Rect<T>[];
+/** The measurements of a packing. */
+interface PackingMetrics {
+  /** The number of rectangles. */
+  count: number;
+  /** The size of the hull: the smallest box around the rectangles. */
+  hull: {
+    width: number;
+    height: number;
+  };
+  /** The width of the hull divided by its height. A hull without height gives 0. */
+  hullAspect: number;
+  /** The number of rectangles in each row, from the top. */
+  rows: number[];
+  /** The largest right edge of a row less the smallest right edge of a row. A straight right side gives 0. */
+  raggedness: number;
+  /** The part of the hull that the rectangles cover: their area divided by the area of the hull. */
+  utilization: number;
+  /** The width of the widest rectangle divided by the median width. */
+  widestOverMedian: number;
+}
+/** The options of `packingMetrics`. */
+interface MetricsOptions {
+  /** A rectangle joins a row when its top is this close to the top of the first rectangle of the row. The default is 40. */
+  rowTolerance?: number;
+}
+/**
+ * This function measures a packing. It gives the hull and its aspect, the rows and the raggedness of the right side.
+ * It also gives the part of the hull that the rectangles cover, and the widest rectangle against the median width.
+ *
+ * @example
+ * ```ts
+ * const { utilization, raggedness } = packingMetrics(Rect.packed(cards));
+ * ```
+ */
+export declare function packingMetrics(rects: readonly Rect[], options?: MetricsOptions): PackingMetrics;
+export type { MetricsOptions, PackLayoutOptions, PackOptions, PackingMetrics, PushOptions, ShelfOptions, SortOrder };
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/vector.ts","../src/rect.ts","../src/order.ts","../src/pack.ts","../src/skyline.ts","../src/shelf.ts","../src/push.ts","../src/metrics.ts"],"mappings":";qBACa;;EAIX,YAAY,YAAO;;MAMf;MACA,EAAE;;MAEF;MACA,EAAE;;EAGN,IAAI,WAAW;;EAMf,MAAM,GAAG;;EAMT,IAAI,OAAO,SAAS;;EAKpB;;EAKA,SAAS;;EAKT,MAAM,KAAK,QAAQ,KAAK,SAAS;;SAQ1B,GAAG,iBAAiB;;SAKpB,IAAI,SAAS,WAAW;;SASxB,IAAI,SAAS,WAAW;;aASpB,YAAY;;;qBCxEZ,KAAK;;;EAKhB,KAAK;;EAEL;;EAEA;;EAEA;;;;;EAKA;;MAGI,YAAY;;MAEZ,QAAQ;;EAGZ;;EAEA;;EAGA,WAAW;;EAOX,YAAY,QAAQ;;EAMpB;;SAGO,OAAO,GAAG,OAAO,KAAK,OAAO,KAAK;;SAKlC,SAAS,GAAG,OAAO,KAAK,OAAO,KAAK;;SAKpC,YAAY,GAAG,OAAO,KAAK;;SAK3B,SAAS,GAAG,OAAO,KAAK;;SAKxB,UAAU,GAAG,OAAO,KAAK;;;;;;KC/DtB;;qBAGC,sBAAsB;;wBAGnB,aAAa,OAAO,aAAa,GAAG,GAAG,KAAK,IAAI,GAAG,KAAK;;UCLvD;;EAEf,YAAY;;;UAIG,0BAA0B;;;;;EAKzC;;;;;;;wBAqEc,SAAS,GAAG,OAAO,KAAK,MAAM,OAAO,KAAK,IAAI,UAAS,cAAmB,KAAK;;;;;;;;;;;wBAiB/E,KAAK,GAAG,OAAO,KAAK,MAAM,QAAO,KAAK,IAAiB,UAAS,oBAAyB,KAAK;;;;;;wBChG9F,aAAa,SAAS,mBAAmB,eAAe;EAAe;EAAW;;;;;;;;;;;;;;wBAiClF,YAAY,GAAG,OAAO,KAAK,MAAM,OAAO,KAAK,IAAI;EAAW,YAAY;IAAmB,KAAK;;UCrC/F;;EAEf,YAAY;;;;;;;;;;;;;;wBAiDE,UAAU,GAAG,OAAO,KAAK,MAAM,OAAO,KAAK,IAAI,UAAS,eAAoB,KAAK;;UCpDhF;;EAEf;;EAEA;;;;;;;;;;;;;wBAqDc,YAAY,GAAG,QAAQ,KAAK,IAAI,gBAAgB,KAAK,MAAM,UAAS,cAAmB,KAAK;;UCzD3F;;EAEf;;EAEA;IAAQ;IAAe;;;EAEvB;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIe;;EAEf;;;;;;;;;;;wBAYc,eAAe,gBAAgB,QAAQ,UAAS,iBAAsB"}