@thi.ng/layout 2.1.34 → 3.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-08-27T11:20:59Z
+- **Last updated**: 2023-10-30T14:31:56Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,20 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [3.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/layout@3.0.0) (2023-10-30)
+
+#### 🛑 Breaking changes
+
+- add IGridLayout generics ([52bad17](https://github.com/thi-ng/umbrella/commit/52bad17))
+- BREAKING CHANGE: IGridLayout requires a generic type now (for `.nest()`)
+  - update GridLayout class
+
+#### 🚀 Features
+
+- add StackedLayout, update types & GridLayout ([1c1281f](https://github.com/thi-ng/umbrella/commit/1c1281f))
+- update StackedLayout.largestSpan() ([9ce54cd](https://github.com/thi-ng/umbrella/commit/9ce54cd))
+  - add optional max. size constraint arg
+
 ## [2.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/layout@2.1.0) (2021-11-17)
 
 #### 🚀 Features

package/README.md

@@ -12,22 +12,27 @@ This project is part of the
 
 - [About](#about)
 - [Status](#status)
+- [Related packages](#related-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
 - [API](#api)
   - [GridLayout](#gridlayout)
+  - [StackedLayout](#stackedlayout)
 - [Authors](#authors)
 - [License](#license)
 
 ## About
 
-Configurable nested 2D grid layout manager.
+Configurable nested 2D grid layout generators.
 
-Currently, this package features only a single grid layout allocator, as
-well as more [generic supporting
-types](https://github.com/thi-ng/umbrella/tree/develop/packages/layout/src/api.ts)
-to define other layout types / implementations.
+Currently, this package features two grid layout strategies (each based on
+requesting/allocating cells of a desired size), as well as more general
+supporting types to define other layout types / implementations using the same
+shared API.
+
+A brief overview and comparison of the available strategies is provided further
+below.
 
 ## Status
 
@@ -35,6 +40,10 @@ to define other layout types / implementations.
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Blayout%5D+in%3Atitle)
 
+## Related packages
+
+- [@thi.ng/imgui](https://github.com/thi-ng/umbrella/tree/develop/packages/imgui) - Immediate mode GUI with flexible state handling & data only shape output
+
 ## Installation
 
 ```bash
@@ -55,25 +64,25 @@ For Node.js REPL:
 const layout = await import("@thi.ng/layout");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 624 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 1.01 KB
 
 ## Dependencies
 
+- [@thi.ng/arrays](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 
 ## Usage examples
 
-Several demos in this repo's
+Several projects in this repo's
 [/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
-directory are using this package.
+directory are using this package:
 
-A selection:
-
-| Screenshot                                                                                                          | Description                                | Live demo                                          | Source                                                                          |
-|:--------------------------------------------------------------------------------------------------------------------|:-------------------------------------------|:---------------------------------------------------|:--------------------------------------------------------------------------------|
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/fft-synth.png" width="240"/>    | Interactive inverse FFT toy synth          | [Demo](https://demo.thi.ng/umbrella/fft-synth/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/fft-synth)    |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/imgui/imgui-all.png" width="240"/>       | Canvas based Immediate Mode GUI components | [Demo](https://demo.thi.ng/umbrella/imgui/)        | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/imgui)        |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/imgui-basics.png" width="240"/> | Minimal IMGUI usage example                | [Demo](https://demo.thi.ng/umbrella/imgui-basics/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/imgui-basics) |
+| Screenshot                                                                                                            | Description                                            | Live demo                                            | Source                                                                            |
+|:----------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------|:-----------------------------------------------------|:----------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/fft-synth.png" width="240"/>      | Interactive inverse FFT toy synth                      | [Demo](https://demo.thi.ng/umbrella/fft-synth/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/fft-synth)      |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/imgui/imgui-all.png" width="240"/>         | Canvas based Immediate Mode GUI components             | [Demo](https://demo.thi.ng/umbrella/imgui/)          | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/imgui)          |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/imgui-basics.png" width="240"/>   | Minimal IMGUI usage example                            | [Demo](https://demo.thi.ng/umbrella/imgui-basics/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/imgui-basics)   |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/layout-gridgen.png" width="240"/> | Randomized space-filling, nested grid layout generator | [Demo](https://demo.thi.ng/umbrella/layout-gridgen/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/layout-gridgen) |
 
 ## API
 
@@ -85,51 +94,181 @@ The `GridLayout` class supports infinite nesting and column/row-based
 space allocation, based on an initial configuration and supporting
 multiple column/row spans.
 
-![screenshot](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/layout/grid-layout.png)
-
-The code producing this structure:
-
-```ts
-import { gridLayout } from "@thi.ng/layout";
-
-// create a single column layout @ position 10,10 / 200px wide
+![screenshot](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/layout/readme-grid.png)
+
+The code producing this layout (incl. the visualization itself):
+
+```ts tangle:export/readme-grid.ts
+import * as g from "@thi.ng/geom";
+import { gridLayout, type LayoutBox } from "@thi.ng/layout";
+import { writeFileSync } from "fs";
+
+// collection of generated layout cells
+const cells: g.Group[] = [];
+
+const addRect = (id: number, box: LayoutBox, fill: string) => {
+    console.log(box);
+    const shape = g.rect([box.x, box.y], [box.w, box.h], { fill });
+    cells.push(
+        g.group({}, [
+            shape,
+            g.text(g.centroid(shape)!, "#" + id, {
+                fill: "black",
+                stroke: "none",
+            }),
+        ])
+    );
+};
+
+// create a single column layout @ position [10,10], 1000px wide
 // the last values are row height and cell spacing
-const layout = gridLayout(10, 10, 200, 1, 16, 4);
+const layout = gridLayout(10, 10, 1000, 1, 60, 4);
 
-// get next layout box (1st row)
-// usually you don't need to call .next() manually, but merely pass
-// the layout instance to a component...
-layout.next();
-// { x: 10, y: 10, w: 200, h: 16, cw: 200, ch: 16, gap: 4 }
+// get next layout box (1st row, by default the column/row span is [1,1])
+addRect(1, layout.next(), "#fec");
+// { x: 10, y: 10, w: 1000, h: 60, cw: 1000, ch: 60, gap: 4, span: [ 1, 1 ] }
 
 // 2nd row
-layout.next();
-// { x: 10, y: 30, w: 200, h: 16, cw: 200, ch: 16, gap: 4 }
+addRect(2, layout.next(), "#fec");
+// { x: 10, y: 74, w: 1000, h: 60, cw: 1000, ch: 60, gap: 4, span: [ 1, 1 ] }
 
 // create nested 2-column layout (3rd row)
 const twoCols = layout.nest(2);
 
-twoCols.next();
-// { x: 10, y: 50, w: 98, h: 16, cw: 98, ch: 16, gap: 4 }
+addRect(3, twoCols.next(), "#cfc");
+// { x: 10, y: 138, w: 498, h: 60, cw: 498, ch: 60, gap: 4, span: [ 1, 1 ] }
 
-twoCols.next();
-// { x: 112, y: 50, w: 98, h: 16, cw: 98, ch: 16, gap: 4 }
+addRect(4, twoCols.next(), "#cfc");
+// { x: 512, y: 138, w: 498, h: 60, cw: 498, ch: 60, gap: 4, span: [ 1, 1 ] }
 
 // now nest 3-columns in the 1st column of twoCols
 // (i.e. now each column is 1/6th of the main layout's width)
 const inner = twoCols.nest(3);
 
 // allocate with col/rowspan, here 1 column x 4 rows
-inner.next([1, 4])
-// { x: 10, y: 70, w: 30, h: 76, cw: 30, ch: 16, gap: 4 }
-inner.next([1, 4])
-// { x: 44, y: 70, w: 30, h: 76, cw: 30, ch: 16, gap: 4 }
-inner.next([1, 4])
-// { x: 78, y: 70, w: 30, h: 76, cw: 30, ch: 16, gap: 4 }
+addRect(5, inner.next([1, 4]), "#9ff");
+// { x: 10, y: 202, w: 163.33, h: 252, cw: 163.33, ch: 60, gap: 4, span: [ 1, 4 ] }
+addRect(6, inner.next([1, 4]), "#9ff");
+// { x: 177.33, y: 202, w: 163.33, h: 252, cw: 163.33, ch: 60, gap: 4, span: [ 1, 4 ] }
+addRect(7, inner.next([1, 4]), "#9ff");
+// { x: 344.66, y: 202, w: 163.33, h: 252, cw: 163.33, ch: 60, gap: 4, span: [ 1, 4 ] }
 
 // back to twoCols (2nd column)
-twoCols.next([1, 2]);
-// { x: 112, y: 70, w: 98, h: 36, cw: 98, ch: 16, gap: 4 }
+addRect(8, twoCols.next([1, 2]), "#cfc");
+// { x: 512, y: 202, w: 498, h: 124, cw: 498, ch: 60, gap: 4, span: [ 1, 2 ] }
+
+// export as SVG
+writeFileSync(
+    "export/readme-grid.svg",
+    g.asSvg(
+        g.svgDoc(
+            {
+                __bleed: 10,
+                font: "12px Menlo, monospace",
+                align: "center",
+                baseline: "middle",
+            },
+            ...cells
+        )
+    )
+);
+```
+
+### StackedLayout
+
+An extension of [GridLayout](#gridlayout) which tracks individual column-based
+heights and so can create more complex, irregular, packed, space-filling layout
+arrangements. This layout algorithm prioritizes the column(s) with the lowest
+height.
+
+This class also provides a
+[`.availableSpan()`](https://docs.thi.ng/umbrella/layout/classes/StackedLayout.html#availableSpan)
+method to find available space and help equalize columns and fill/allocate any
+bottom gaps.
+
+IMPORTANT: As with GridLayout, nested layouts **MUST** be completed first before
+requesting new cells (aka `LayoutBoxes`) from a parent, otherwise unintended
+overlaps will occur.
+
+![screenshot](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/layout/readme-stacked.png)
+
+The code producing this layout (incl. the visualization itself):
+
+```ts tangle:export/readme-stacked.ts
+import * as g from "@thi.ng/geom";
+import { stackedLayout, type LayoutBox } from "@thi.ng/layout";
+import { writeFileSync } from "fs";
+
+// collection of generated layout cells
+const cells: g.Group[] = [];
+
+const addRect = (id: number, box: LayoutBox, fill: string) => {
+    console.log(box);
+    const shape = g.rect([box.x, box.y], [box.w, box.h], { fill });
+    cells.push(
+        g.group({}, [
+            shape,
+            g.text(g.centroid(shape)!, "#" + id, {
+                fill: "black",
+                stroke: "none",
+            }),
+        ])
+    );
+};
+
+// create a 4-column layout @ position [0,0], 1000px wide
+// the last values are row height and cell spacing
+const layout = stackedLayout(0, 0, 1000, 4, 60, 4);
+
+// get next layout box (1st column)
+addRect(1, layout.next([1, 2]), "#fec");
+// { x: 0, y: 0, w: 247, h: 124, cw: 247, ch: 60, gap: 4, span: [ 1, 2 ] }
+
+// 2nd column
+addRect(2, layout.next(), "#fec");
+// { x: 251, y: 0, w: 247, h: 60, cw: 247, ch: 60, gap: 4, span: [ 1, 1 ] }
+
+// 3rd column
+addRect(3, layout.next([1, 4]), "#fec");
+// { x: 502, y: 0, w: 247, h: 252, cw: 247, ch: 60, gap: 4, span: [ 1, 4 ] }
+
+// 4th column
+addRect(4, layout.next([1, 1]), "#fec");
+// { x: 753, y: 0, w: 247, h: 60, cw: 247, ch: 60, gap: 4, span: [ 1, 1 ] }
+
+// 2x2 span
+// (note that this will create a gap in the 2nd column)
+addRect(5, layout.next([2, 2]), "#fec");
+// { x: 0, y: 128, w: 498, h: 124, cw: 247, ch: 60, gap: 4, span: [ 2, 2 ] }
+
+const inner = layout.nest(2);
+
+addRect(6, inner.next([1, 5]), "#cfc");
+// { x: 753, y: 64, w: 121.5, h: 316, cw: 121.5, ch: 60, gap: 4, span: [ 1, 5 ] }
+addRect(7, inner.next([1, 5]), "#cfc");
+// { x: 878.5, y: 64, w: 121.5, h: 316, cw: 121.5, ch: 60, gap: 4, span: [ 1, 5 ] }
+
+// fill available space in the other columns
+// (depending on situation, this might have to be done multiple times
+// to fill all available space, please consult documentation)
+addRect(8, layout.next(layout.availableSpan()), "#9ff");
+// { x: 0, y: 256, w: 749, h: 124, cw: 247, ch: 60, gap: 4, span: [ 3, 2 ] }
+
+// export as SVG
+writeFileSync(
+    "export/readme-stacked.svg",
+    g.asSvg(
+        g.svgDoc(
+            {
+                __bleed: 10,
+                font: "12px Menlo, monospace",
+                align: "center",
+                baseline: "middle",
+            },
+            ...cells
+        )
+    )
+);
 ```
 
 ## Authors

package/api.d.ts

@@ -1,3 +1,4 @@
+export type CellSpan = [number, number];
 export interface LayoutBox {
     /**
      * Top-left corner X
@@ -29,11 +30,15 @@ export interface LayoutBox {
      * Gutter size.
      */
     gap: number;
+    /**
+     *
+     */
+    span: CellSpan;
 }
 export interface ILayout<O, T> {
     next(opts?: O): T;
 }
-export interface IGridLayout extends ILayout<[number, number], LayoutBox> {
+export interface IGridLayout<T extends IGridLayout<T>> extends ILayout<CellSpan, LayoutBox> {
     readonly x: number;
     readonly y: number;
     readonly width: number;
@@ -59,8 +64,8 @@ export interface IGridLayout extends ILayout<[number, number], LayoutBox> {
      *
      * @param size -
      */
-    spansForSize(size: ArrayLike<number>): [number, number];
-    spansForSize(w: number, h: number): [number, number];
+    spanForSize(size: ArrayLike<number>): CellSpan;
+    spanForSize(w: number, h: number): CellSpan;
     /**
      * Returns a squared {@link LayoutBox} based on this layout's column
      * width. This box will consume `ceil(columnWidth / rowHeight)`
@@ -104,7 +109,8 @@ export interface IGridLayout extends ILayout<[number, number], LayoutBox> {
      *
      * @param cols - columns in nested layout
      * @param spans - default [1, 1] (i.e. size of single cell)
+     * @param gap - gap for child layout
      */
-    nest(cols: number, spans?: [number, number]): IGridLayout;
+    nest(cols: number, spans?: CellSpan, gap?: number): T;
 }
 //# sourceMappingURL=api.d.ts.map

package/box.d.ts

@@ -1,3 +1,3 @@
-import type { LayoutBox } from "./api.js";
-export declare const layoutBox: (x: number, y: number, w: number, h: number, cw: number, ch: number, gap: number) => LayoutBox;
+import type { CellSpan, LayoutBox } from "./api.js";
+export declare const layoutBox: (x: number, y: number, w: number, h: number, cw: number, ch: number, gap: number, span?: CellSpan) => LayoutBox;
 //# sourceMappingURL=box.d.ts.map

package/box.js

@@ -1 +1,10 @@
-export const layoutBox = (x, y, w, h, cw, ch, gap) => ({ x, y, w, h, cw, ch, gap });
+export const layoutBox = (x, y, w, h, cw, ch, gap, span) => ({
+    x,
+    y,
+    w,
+    h,
+    cw,
+    ch,
+    gap,
+    span: span || [~~(w / cw), ~~(h / ch)],
+});

package/grid-layout.d.ts

@@ -1,5 +1,7 @@
-import type { IGridLayout, LayoutBox } from "./api.js";
-export declare class GridLayout implements IGridLayout {
+import type { CellSpan, IGridLayout, LayoutBox } from "./api.js";
+/** @internal */
+export declare const __DEFAULT_SPANS: CellSpan;
+export declare class GridLayout implements IGridLayout<GridLayout> {
     readonly parent: GridLayout | null;
     readonly cols: number;
     readonly width: number;
@@ -16,17 +18,17 @@ export declare class GridLayout implements IGridLayout {
     constructor(parent: GridLayout | null, x: number, y: number, width: number, cols: number, rowH: number, gap: number);
     colsForWidth(w: number): number;
     rowsForHeight(h: number): number;
-    spansForSize(size: ArrayLike<number>): [number, number];
-    spansForSize(w: number, h: number): [number, number];
-    next(spans?: [number, number]): LayoutBox;
+    spanForSize(size: ArrayLike<number>): CellSpan;
+    spanForSize(w: number, h: number): CellSpan;
+    next(spans?: CellSpan): LayoutBox;
     nextSquare(): LayoutBox;
-    nest(cols: number, spans?: [number, number]): GridLayout;
+    nest(cols: number, spans?: CellSpan, gap?: number): GridLayout;
     /**
      * Updates max rows used in this layout and all of its parents.
      *
      * @param rspan -
      */
-    protected propagateSize(rspan: number): void;
+    propagateSize(rspan: number): void;
 }
 /**
  * Syntax sugar for {@link GridLayout} ctor. By default creates a

package/grid-layout.js

@@ -1,5 +1,6 @@
 import { isNumber } from "@thi.ng/checks/is-number";
-const DEFAULT_SPANS = [1, 1];
+/** @internal */
+export const __DEFAULT_SPANS = [1, 1];
 export class GridLayout {
     constructor(parent, x, y, width, cols, rowH, gap) {
         this.parent = parent;
@@ -22,11 +23,11 @@ export class GridLayout {
     rowsForHeight(h) {
         return Math.ceil(h / this.cellHG);
     }
-    spansForSize(w, h) {
+    spanForSize(w, h) {
         const size = isNumber(w) ? [w, h] : w;
         return [this.colsForWidth(size[0]), this.rowsForHeight(size[1])];
     }
-    next(spans = DEFAULT_SPANS) {
+    next(spans = __DEFAULT_SPANS) {
         const { cellWG, cellHG, gap, cols } = this;
         const cspan = Math.min(spans[0], cols);
         const rspan = spans[1];
@@ -48,11 +49,13 @@ export class GridLayout {
             cw: this.cellW,
             ch: this.cellH,
             gap,
+            span: [cspan, rspan],
         };
         this.propagateSize(rspan);
         this.currCol = Math.min(this.currCol + cspan, cols) % cols;
         return cell;
     }
+    // TODO add optional colspan arg, fix rounding
     nextSquare() {
         const box = this.next([
             1,
@@ -61,9 +64,9 @@ export class GridLayout {
         box.h = box.w;
         return box;
     }
-    nest(cols, spans) {
+    nest(cols, spans, gap = this.gap) {
         const { x, y, w } = this.next(spans);
-        return new GridLayout(this, x, y, w, cols, this.cellH, this.gap);
+        return new GridLayout(this, x, y, w, cols, this.cellH, gap);
     }
     /**
      * Updates max rows used in this layout and all of its parents.

package/index.d.ts

@@ -2,4 +2,5 @@ export * from "./api.js";
 export * from "./box.js";
 export * from "./checks.js";
 export * from "./grid-layout.js";
+export * from "./stacked-layout.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -2,3 +2,4 @@ export * from "./api.js";
 export * from "./box.js";
 export * from "./checks.js";
 export * from "./grid-layout.js";
+export * from "./stacked-layout.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/layout",
-  "version": "2.1.34",
-  "description": "Configurable nested 2D grid layout manager",
+  "version": "3.0.0",
+  "description": "Configurable nested 2D grid layout generators",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -34,14 +34,15 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/checks": "^3.4.5"
+    "@thi.ng/arrays": "^2.7.1",
+    "@thi.ng/checks": "^3.4.6"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.36.4",
-    "@thi.ng/testament": "^0.3.23",
-    "rimraf": "^5.0.1",
+    "@microsoft/api-extractor": "^7.38.0",
+    "@thi.ng/testament": "^0.3.24",
+    "rimraf": "^5.0.5",
     "tools": "^0.0.1",
-    "typedoc": "^0.25.0",
+    "typedoc": "^0.25.2",
     "typescript": "^5.2.2"
   },
   "keywords": [
@@ -81,10 +82,16 @@
     },
     "./grid-layout": {
       "default": "./grid-layout.js"
+    },
+    "./stacked-layout": {
+      "default": "./stacked-layout.js"
     }
   },
   "thi.ng": {
+    "related": [
+      "imgui"
+    ],
     "year": 2019
   },
-  "gitHead": "5929dd20497668496af13415cdf784a4d6f69aa3\n"
+  "gitHead": "bfa16829786146bd24df3cdbd44649a45a603e44\n"
 }

package/stacked-layout.d.ts

@@ -0,0 +1,52 @@
+import type { CellSpan, LayoutBox } from "./api.js";
+import { GridLayout } from "./grid-layout.js";
+/**
+ * An extension of {@link GridLayout} which tracks individual column-based
+ * heights and so can create more complex, irregular, packed, space-filling
+ * layout arrangements. This layout algorithm prioritizes the column(s) with the
+ * lowest height.
+ *
+ * The class also provides a {@link StackedLayout.availableSpan} method to find
+ * available space and help equalize columns and fill/allocate any bottom gaps.
+ *
+ * **IMPORTANT:** As with {@link GridLayout}, nested layouts MUST be completed
+ * first before requesting new cells (aka {@link LayoutBox}es) from a parent,
+ * otherwise unintended overlaps will occur.
+ */
+export declare class StackedLayout extends GridLayout {
+    offsets: Uint32Array;
+    currSpan: number;
+    constructor(parent: GridLayout | null, x: number, y: number, width: number, cols: number, rowH: number, gap: number);
+    nest(cols: number, spans?: CellSpan, gap?: number): StackedLayout;
+    next(spans?: CellSpan): LayoutBox;
+    /**
+     * Finds the largest available span of free area, such that if it'll be
+     * allocated via {@link StackedLayout.next} or {@link StackedLayout.nest},
+     * the impacted columns will all have the same height, and that height will
+     * match that of the next column after (if any). Repeated use of this method
+     * can be used to fill up (aka equalize) any bottom gaps of a layout
+     * container until all columns are equal. If the function returns a vertical
+     * span of 0, all columns are equalized already.
+     *
+     * @remarks
+     * An optional `maxSpan` can be provided to constrain the returned span (by
+     * default unconstrained).
+     *
+     * @param maxSpan
+     */
+    availableSpan(maxSpan?: CellSpan): CellSpan;
+    propagateSize(rspan: number): void;
+}
+/**
+ * Syntax sugar for {@link StackedLayout} ctor. By default creates a 4-column
+ * layout at given position and total width.
+ *
+ * @param x -
+ * @param y -
+ * @param width -
+ * @param cols -
+ * @param rowH -
+ * @param gap -
+ */
+export declare const stackedLayout: (x: number, y: number, width: number, cols?: number, rowH?: number, gap?: number) => StackedLayout;
+//# sourceMappingURL=stacked-layout.d.ts.map

package/stacked-layout.js

@@ -0,0 +1,110 @@
+import { argMax, argMin } from "@thi.ng/arrays/argmin";
+import { GridLayout, __DEFAULT_SPANS } from "./grid-layout.js";
+/**
+ * An extension of {@link GridLayout} which tracks individual column-based
+ * heights and so can create more complex, irregular, packed, space-filling
+ * layout arrangements. This layout algorithm prioritizes the column(s) with the
+ * lowest height.
+ *
+ * The class also provides a {@link StackedLayout.availableSpan} method to find
+ * available space and help equalize columns and fill/allocate any bottom gaps.
+ *
+ * **IMPORTANT:** As with {@link GridLayout}, nested layouts MUST be completed
+ * first before requesting new cells (aka {@link LayoutBox}es) from a parent,
+ * otherwise unintended overlaps will occur.
+ */
+export class StackedLayout extends GridLayout {
+    constructor(parent, x, y, width, cols, rowH, gap) {
+        super(parent, x, y, width, cols, rowH, gap);
+        this.currSpan = 1;
+        this.offsets = new Uint32Array(cols);
+    }
+    nest(cols, spans, gap = this.gap) {
+        const { x, y, w } = this.next(spans);
+        return new StackedLayout(this, x, y, w, cols, this.cellH, gap);
+    }
+    next(spans = __DEFAULT_SPANS) {
+        const { cellWG, cellHG, gap, cols, offsets } = this;
+        const cspan = Math.min(spans[0], cols);
+        const rspan = spans[1];
+        let minY = Infinity;
+        let maxY = 0;
+        let column = 0;
+        for (let i = 0; i <= cols - cspan; i++) {
+            const chunk = offsets.subarray(i, i + cspan);
+            const maxID = argMax(chunk);
+            const y = chunk[maxID];
+            if (y < minY) {
+                minY = y;
+                maxY = chunk[maxID];
+                column = i;
+            }
+        }
+        const h = rspan * cellHG - gap;
+        const cell = {
+            x: this.x + column * cellWG,
+            y: this.y + maxY * cellHG,
+            w: cspan * cellWG - gap,
+            h,
+            cw: this.cellW,
+            ch: this.cellH,
+            gap,
+            span: [cspan, rspan],
+        };
+        this.currRow = maxY;
+        this.currCol = column;
+        offsets.fill(maxY + rspan, column, column + cspan);
+        this.currSpan = cspan;
+        this.parent && this.parent.propagateSize(Math.max(...this.offsets));
+        return cell;
+    }
+    /**
+     * Finds the largest available span of free area, such that if it'll be
+     * allocated via {@link StackedLayout.next} or {@link StackedLayout.nest},
+     * the impacted columns will all have the same height, and that height will
+     * match that of the next column after (if any). Repeated use of this method
+     * can be used to fill up (aka equalize) any bottom gaps of a layout
+     * container until all columns are equal. If the function returns a vertical
+     * span of 0, all columns are equalized already.
+     *
+     * @remarks
+     * An optional `maxSpan` can be provided to constrain the returned span (by
+     * default unconstrained).
+     *
+     * @param maxSpan
+     */
+    availableSpan(maxSpan = [Infinity, Infinity]) {
+        const { offsets, cols } = this;
+        const minID = argMin(offsets);
+        const y = offsets[minID];
+        let result;
+        for (let i = minID + 1; i < cols; i++) {
+            if (offsets[i] > y) {
+                result = [i - minID, offsets[i] - y];
+                break;
+            }
+        }
+        if (!result)
+            result = [cols - minID, offsets[argMax(offsets)] - y];
+        result[0] = Math.min(result[0], maxSpan[0]);
+        result[1] = Math.min(result[1], maxSpan[1]);
+        return result;
+    }
+    propagateSize(rspan) {
+        const newY = Math.max(this.currRow + rspan, this.offsets[this.currCol]);
+        this.offsets.fill(newY, this.currCol, this.currCol + this.currSpan);
+        this.parent && this.parent.propagateSize(newY);
+    }
+}
+/**
+ * Syntax sugar for {@link StackedLayout} ctor. By default creates a 4-column
+ * layout at given position and total width.
+ *
+ * @param x -
+ * @param y -
+ * @param width -
+ * @param cols -
+ * @param rowH -
+ * @param gap -
+ */
+export const stackedLayout = (x, y, width, cols = 4, rowH = 16, gap = 4) => new StackedLayout(null, x, y, width, cols, rowH, gap);