xonecas.io
70160
Ce

cel-tui / commit ad6095c

feat(core): add measureContentHeight helper

xonecas2026-04-08 ad6095c5d71ace989da47dadf4f7e8690275bdc1 parent c2c4c6e

6 files changed

docs/skill/cel-tui/SKILL.md+17−0
@@ -143,6 +143,23 @@ VStack(
143143
144144 Controlled mode enables patterns like auto-scroll to bottom on new content. `scrollStep` affects mouse wheel input only — not programmatic `scrollOffset` updates.
145145
146+### Measuring content height
147+
148+Use `measureContentHeight(node, { width })` when your app knows the wrapping width but needs to know how tall a content subtree will be.
149+
150+```ts
151+import { measureContentHeight, VStack } from "@cel-tui/core";
152+
153+const addedHeight = measureContentHeight(
154+ VStack({}, olderMessages.map(renderMessage)),
155+ { width: historyContentWidth },
156+);
157+
158+scrollOffset += addedHeight;
159+```
160+
161+This is for **intrinsic content measurement**, not viewport/clipping measurement. The provided `width` is authoritative. Measure the content subtree you are adding or anchoring around — not a wrapper whose visible height is controlled by `height`, `flex`, or percentage sizing. If you measure a padded container, pass its outer width; if you measure the children inside a padded container directly, pass the inner content width.
162+
146163 ### Layers (modals)
147164
148165 Return an array from the render function — layers composite bottom-to-top:
docs/skill/cel-tui/references/api.md+22−0
@@ -37,6 +37,28 @@ All props accepted by `VStack` and `HStack`:
3737 }
3838 ```
3939
40+## Measurement Helpers
41+
42+```ts
43+measureContentHeight(node, { width }); // number
44+```
45+
46+- Measures a node tree's **intrinsic content height** at the provided wrapping width.
47+- This is a content-measurement helper, not a viewport/clipping helper.
48+- The provided `width` is authoritative — use the actual width the subtree wraps at.
49+- Main use case: prepend-style scrollback, where older content is inserted above the current viewport and the app needs to preserve the viewport anchor.
50+
51+```ts
52+const addedHeight = measureContentHeight(
53+ VStack({}, olderMessages.map(renderMessage)),
54+ { width: historyContentWidth },
55+);
56+
57+scrollOffset += addedHeight;
58+```
59+
60+Measure the content subtree you are adding. If a wrapper's visible height is controlled by `height`, `flex`, or percentage sizing, measure the content inside that wrapper instead. For padded content, pass the outer width when measuring the padded container itself, or the inner content width when measuring its children directly.
61+
4062 ## Scroll
4163
4264 Scroll supports **uncontrolled** (default) and **controlled** modes, mirroring the focus model:
packages/core/src/index.ts+4−2
@@ -2,8 +2,9 @@
22 * @module @cel-tui/core
33 *
44 * Core framework package. Provides the four primitives ({@link VStack},
5- * {@link HStack}, {@link Text}, {@link TextInput}) and the framework
6- * entrypoint ({@link cel}).
5+ * {@link HStack}, {@link Text}, {@link TextInput}), the framework
6+ * entrypoint ({@link cel}), and measurement helpers such as
7+ * {@link measureContentHeight}.
78 *
89 * All types are re-exported from `@cel-tui/types`.
910 *
@@ -45,6 +46,7 @@ export { VStack, HStack } from "./primitives/stacks.js";
4546 export { Text } from "./primitives/text.js";
4647 export { TextInput } from "./primitives/text-input.js";
4748 export { cel } from "./cel.js";
49+export { measureContentHeight } from "./layout.js";
4850 export { CellBuffer, EMPTY_CELL, type Cell } from "./cell-buffer.js";
4951 export { emitBuffer, defaultTheme } from "./emitter.js";
5052 export { visibleWidth, extractAnsiCode } from "./width.js";
packages/core/src/layout.test.ts+86−0
@@ -1,4 +1,5 @@
11 import { describe, expect, test } from "bun:test";
2+import { measureContentHeight } from "./index.js";
23 import { layout, type LayoutNode, type Rect } from "./layout.js";
34 import { VStack, HStack } from "./primitives/stacks.js";
45 import { Text } from "./primitives/text.js";
@@ -1247,4 +1248,89 @@ describe("layout", () => {
12471248 expect(result.children[1]!.rect.y).toBe(3);
12481249 });
12491250 });
1251+
1252+ describe("measureContentHeight", () => {
1253+ test("wrapped Text returns the visual line count for the provided width", () => {
1254+ // Arrange
1255+ const node = Text("foo bar baz", { wrap: "word" });
1256+
1257+ // Act
1258+ const height = measureContentHeight(node, { width: 6 });
1259+
1260+ // Assert
1261+ expect(height).toBe(3);
1262+ });
1263+
1264+ test("padded VStack accounts for its own padding when measuring children", () => {
1265+ // Arrange
1266+ const node = VStack({ padding: { x: 1, y: 1 }, gap: 1 }, [
1267+ Text("foo bar", { wrap: "word" }),
1268+ Text("baz"),
1269+ ]);
1270+
1271+ // Act
1272+ const height = measureContentHeight(node, { width: 8 });
1273+
1274+ // Assert
1275+ expect(height).toBe(6);
1276+ });
1277+
1278+ test("wrapping HStack returns the sum of row heights plus row gaps", () => {
1279+ // Arrange
1280+ const node = HStack({ flexWrap: "wrap", gap: 1 }, [
1281+ VStack({ width: 5, height: 2 }, []),
1282+ VStack({ width: 5, height: 3 }, []),
1283+ VStack({ width: 5, height: 4 }, []),
1284+ ]);
1285+
1286+ // Act
1287+ const height = measureContentHeight(node, { width: 11 });
1288+
1289+ // Assert
1290+ expect(height).toBe(8);
1291+ });
1292+
1293+ test("TextInput returns wrapped content height including its own padding", () => {
1294+ // Arrange
1295+ const node = TextInput({
1296+ padding: { x: 1, y: 1 },
1297+ value: "foo bar baz",
1298+ onChange: () => {},
1299+ });
1300+
1301+ // Act
1302+ const height = measureContentHeight(node, { width: 8 });
1303+
1304+ // Assert
1305+ expect(height).toBe(5);
1306+ });
1307+
1308+ test("explicit root height does not limit the measured content height", () => {
1309+ // Arrange
1310+ const node = VStack({ height: 1 }, [
1311+ Text("line 1"),
1312+ Text("line 2"),
1313+ Text("line 3"),
1314+ ]);
1315+
1316+ // Act
1317+ const height = measureContentHeight(node, { width: 10 });
1318+
1319+ // Assert
1320+ expect(height).toBe(3);
1321+ });
1322+
1323+ test("caller-provided width overrides the measured root width prop", () => {
1324+ // Arrange
1325+ const node = VStack({ width: 10 }, [
1326+ Text("foo bar baz", { wrap: "word" }),
1327+ ]);
1328+
1329+ // Act
1330+ const height = measureContentHeight(node, { width: 100 });
1331+
1332+ // Assert
1333+ expect(height).toBe(1);
1334+ });
1335+ });
12501336 });
packages/core/src/layout.ts+44−1
@@ -121,6 +121,15 @@ function intrinsicMainSize(
121121 resolveSizeValue(cProps?.width, 0) ??
122122 intrinsicMainSize(child, false, innerCross);
123123 }
124+ if (cProps) {
125+ const minMain = isVertical
126+ ? (cProps.minHeight ?? 0)
127+ : (cProps.minWidth ?? 0);
128+ const maxMain = isVertical
129+ ? (cProps.maxHeight ?? Infinity)
130+ : (cProps.maxWidth ?? Infinity);
131+ childMain = clamp(childMain, minMain, maxMain);
132+ }
124133 total += childMain;
125134 if (i < node.children.length - 1) total += gap;
126135 }
@@ -150,9 +159,12 @@ function intrinsicMainSize(
150159 }
151160 }
152161 wrapWidths.push(w);
153- const h =
162+ let h =
154163 resolveSizeValue(cProps?.height, 0) ??
155164 intrinsicMainSize(child, true, innerCross);
165+ if (cProps) {
166+ h = clamp(h, cProps.minHeight ?? 0, cProps.maxHeight ?? Infinity);
167+ }
156168 wrapHeights.push(h);
157169 }
158170 const wrapRows = assignWrapRows(wrapWidths, innerCross, gap);
@@ -259,6 +271,37 @@ function largestRemainder(fractions: number[], total: number): number[] {
259271
260272 // --- Main layout ---
261273
274+/**
275+ * Measure a node tree's intrinsic content height at the provided width.
276+ *
277+ * This is a content-measurement helper, not a viewport/clipping helper.
278+ * The caller-provided `width` is the authoritative wrapping width for the
279+ * measured subtree. Measurement starts at the given node, ignores that
280+ * node's own main-axis height constraints, and walks downward through its
281+ * descendants. Descendant sizing rules still apply normally.
282+ *
283+ * Use this for intrinsically sized content such as scrollback/message
284+ * history chunks. If a wrapper's visible height is controlled by `height`,
285+ * `flex`, or percentage sizing, measure the content subtree inside that
286+ * wrapper instead.
287+ *
288+ * @example
289+ * ```ts
290+ * const addedHeight = measureContentHeight(
291+ * VStack({}, olderMessages.map(renderMessage)),
292+ * { width: historyContentWidth },
293+ * );
294+ *
295+ * scrollOffset += addedHeight;
296+ * ```
297+ */
298+export function measureContentHeight(
299+ node: Node,
300+ options: { width: number },
301+): number {
302+ return intrinsicMainSize(node, true, options.width);
303+}
304+
262305 /**
263306 * Compute the layout for a UI tree.
264307 *
spec.md+25−0
@@ -21,6 +21,18 @@ cel.render()
2121
2222 State is fully external to the framework. Use any state management approach — plain variables, classes, libraries. The framework just calls the render function and renders the returned tree.
2323
24+### Measurement Helpers
25+
26+```ts
27+measureContentHeight(node: Node, options: { width: number }): number
28+```
29+
30+Measures a node tree's **intrinsic content height** in terminal cells when wrapped within the provided width. The measurement walks downward from the given node and follows the same content rules as layout: text wrapping, padding, gap, intrinsic container sizing, fixed-size descendants, wrapping HStacks, and TextInput content height.
31+
32+This helper is for **content subtrees** whose height is not externally constrained. Typical use cases: scrollback/message history chunks, prepend-anchor preservation, markdown blocks, and any other intrinsically sized content. It is **not** a viewport measurement API — if a container's visible height is determined by `height`, `flex`, or percentage sizing, measure the content subtree inside that container instead.
33+
34+`width` should be the actual wrapping width for the node being measured. If you measure a padded container, pass its outer width so the helper can account for that container's own padding. If you measure the children inside a padded container directly, pass the inner content width.
35+
2436 ### Primitives
2537
2638 | Category | Primitive | Description |
@@ -266,6 +278,19 @@ VStack({
266278
267279 While `stickToBottom` is true, `Infinity` is clamped to the current maximum on each render — new content automatically scrolls into view. When the user scrolls up, `stickToBottom` becomes false and the explicit offset takes over. Scrolling back to the bottom re-enables sticky mode.
268280
281+For prepend-style scrollback, apps can preserve the current viewport anchor by measuring the height of the newly inserted content and increasing `scrollOffset` by that amount:
282+
283+```ts
284+const addedHeight = measureContentHeight(
285+ VStack({}, olderMessages.map(renderMessage)),
286+ { width: historyContentWidth },
287+);
288+
289+scrollOffset += addedHeight;
290+```
291+
292+`historyContentWidth` is the width the inserted content actually wraps at. For a padded scroll container, that usually means the container's inner content width.
293+
269294 ---
270295
271296 ## Scroll Input Model