xonecas.io
70160
Ce

cel-tui / commit 6ec5bea

feat(core): implement justifyContent and alignItems layout

justifyContent distributes children along the main axis:
- start (default), end, center, space-between
- space-between uses largest-remainder rounding for integer gaps

alignItems positions children along the cross axis:
- stretch (default, fills cross axis)
- start, end, center
- Non-stretch modes use intrinsic cross-axis sizing so children
  without explicit cross size are measured to fit content

Also adds tmux visual testing docs to AGENTS.md and marks
justifyContent/alignItems done in TODO.md.

xonecas2026-04-03 6ec5bea2b38014ccc5def73748369da2cb4fa186 parent 9e3dfab

5 files changed

.gitignore+1−0
@@ -4,3 +4,4 @@ docs/html/
44 docs/md/
55 bun.lockb
66 *.tsbuildinfo
7+assets/Screencast_20260403_190352.webm
AGENTS.md+26−0
@@ -50,6 +50,32 @@ bun run typecheck # tsc --noEmit type checking
5050 bun run docs # generate HTML + Markdown docs into docs/
5151 ```
5252
53+## Visual Testing with tmux
54+
55+Use a tmux session to run examples and visually inspect rendered output:
56+
57+```bash
58+# Create a session (set size to simulate a terminal window)
59+tmux new-session -d -s cel -x 80 -y 24
60+
61+# Run an example
62+tmux send-keys -t cel "cd /home/xonecas/src/cel-tui && bun run examples/hello.ts" Enter
63+
64+# Wait for render, then capture the screen contents
65+sleep 1; tmux capture-pane -t cel -p
66+
67+# Send keystrokes (e.g., Ctrl+Q to quit)
68+tmux send-keys -t cel C-q
69+
70+# Resize the window to test different terminal sizes
71+tmux resize-window -t cel -x 60 -y 20
72+
73+# Kill the session when done
74+tmux kill-session -t cel
75+```
76+
77+This lets you see exactly what the user sees — rendered cells, alignment, clipping, colors — without needing a real interactive terminal.
78+
5379 ## Spec
5480
5581 The `spec.md` file is the source of truth for all API design decisions. Always read it before making changes to core framework behavior. The open questions at the bottom track what's been decided vs. still in progress.
TODO.md+2−2
@@ -19,8 +19,8 @@ What's implemented, what's missing, and what needs hardening. Reference `spec.md
1919 - ✅ Constraints (`minWidth`, `maxWidth`, `minHeight`, `maxHeight`)
2020 - ✅ Gap spacing between children
2121 - ✅ Padding (`{ x, y }`)
22-- ❌ `justifyContent` — positions are computed but alignment offsets not applied (`"start"`, `"end"`, `"center"`, `"space-between"`)
23-- ❌ `alignItems` — cross-axis alignment not applied (`"start"`, `"end"`, `"center"`, `"stretch"`)
22+- ✅ `justifyContent` — `"start"`, `"end"`, `"center"`, `"space-between"`
23+- ✅ `alignItems` — `"start"`, `"end"`, `"center"`, `"stretch"`
2424
2525 ## Rendering
2626
packages/core/src/layout.test.ts+260−0
@@ -353,6 +353,266 @@ describe("layout", () => {
353353 });
354354 });
355355
356+ describe("justifyContent", () => {
357+ test("start is the default (no offset)", () => {
358+ const node = VStack({ width: 80, height: 24, justifyContent: "start" }, [
359+ VStack({ height: 3 }, []),
360+ VStack({ height: 3 }, []),
361+ ]);
362+ const result = layout(node, 80, 24);
363+ const rects = childRects(result);
364+ expect(rects[0]!.y).toBe(0);
365+ expect(rects[1]!.y).toBe(3);
366+ });
367+
368+ test("end pushes children to the end of the main axis", () => {
369+ const node = VStack({ width: 80, height: 24, justifyContent: "end" }, [
370+ VStack({ height: 3 }, []),
371+ VStack({ height: 3 }, []),
372+ ]);
373+ const result = layout(node, 80, 24);
374+ const rects = childRects(result);
375+ // remaining = 24 - 6 = 18
376+ expect(rects[0]!.y).toBe(18);
377+ expect(rects[1]!.y).toBe(21);
378+ });
379+
380+ test("center centers children on the main axis", () => {
381+ const node = VStack({ width: 80, height: 24, justifyContent: "center" }, [
382+ VStack({ height: 3 }, []),
383+ VStack({ height: 3 }, []),
384+ ]);
385+ const result = layout(node, 80, 24);
386+ const rects = childRects(result);
387+ // remaining = 24 - 6 = 18, offset = 9
388+ expect(rects[0]!.y).toBe(9);
389+ expect(rects[1]!.y).toBe(12);
390+ });
391+
392+ test("space-between distributes space between children", () => {
393+ const node = VStack(
394+ { width: 80, height: 24, justifyContent: "space-between" },
395+ [
396+ VStack({ height: 3 }, []),
397+ VStack({ height: 3 }, []),
398+ VStack({ height: 3 }, []),
399+ ],
400+ );
401+ const result = layout(node, 80, 24);
402+ const rects = childRects(result);
403+ // remaining = 24 - 9 = 15, gaps = 2, space per gap = 7.5 → 8, 7
404+ expect(rects[0]!.y).toBe(0);
405+ // gap after first = floor(15/2) or largest-remainder?
406+ // 15 / 2 = 7.5 each → 8, 7 via largest remainder
407+ expect(rects[1]!.y).toBe(3 + 8); // 11
408+ expect(rects[2]!.y).toBe(3 + 8 + 3 + 7); // 21
409+ });
410+
411+ test("space-between with single child acts like start", () => {
412+ const node = VStack(
413+ { width: 80, height: 24, justifyContent: "space-between" },
414+ [VStack({ height: 3 }, [])],
415+ );
416+ const result = layout(node, 80, 24);
417+ expect(childRects(result)[0]!.y).toBe(0);
418+ });
419+
420+ test("center in HStack centers horizontally", () => {
421+ const node = HStack({ width: 80, height: 24, justifyContent: "center" }, [
422+ VStack({ width: 10, height: 24 }, []),
423+ VStack({ width: 10, height: 24 }, []),
424+ ]);
425+ const result = layout(node, 80, 24);
426+ const rects = childRects(result);
427+ // remaining = 80 - 20 = 60, offset = 30
428+ expect(rects[0]!.x).toBe(30);
429+ expect(rects[1]!.x).toBe(40);
430+ });
431+
432+ test("end in HStack pushes children right", () => {
433+ const node = HStack({ width: 80, height: 24, justifyContent: "end" }, [
434+ VStack({ width: 20, height: 24 }, []),
435+ ]);
436+ const result = layout(node, 80, 24);
437+ expect(childRects(result)[0]!.x).toBe(60);
438+ });
439+
440+ test("justifyContent with padding", () => {
441+ const node = VStack(
442+ {
443+ width: 80,
444+ height: 24,
445+ justifyContent: "center",
446+ padding: { y: 2 },
447+ },
448+ [VStack({ height: 4 }, [])],
449+ );
450+ const result = layout(node, 80, 24);
451+ // inner height = 24 - 4 = 20, remaining = 20 - 4 = 16, offset = 8
452+ // child y = padY + offset = 2 + 8 = 10
453+ expect(childRects(result)[0]!.y).toBe(10);
454+ });
455+
456+ test("justifyContent with gap", () => {
457+ const node = VStack(
458+ { width: 80, height: 24, justifyContent: "end", gap: 2 },
459+ [VStack({ height: 3 }, []), VStack({ height: 3 }, [])],
460+ );
461+ const result = layout(node, 80, 24);
462+ const rects = childRects(result);
463+ // total content = 3 + 2 + 3 = 8, remaining = 24 - 8 = 16
464+ expect(rects[0]!.y).toBe(16);
465+ expect(rects[1]!.y).toBe(21); // 16 + 3 + 2
466+ });
467+ });
468+
469+ describe("alignItems", () => {
470+ test("stretch is the default (children fill cross axis)", () => {
471+ const node = VStack({ width: 80, height: 24 }, [
472+ VStack({ height: 3 }, []),
473+ ]);
474+ const result = layout(node, 80, 24);
475+ // cross axis = width, should fill parent
476+ expect(childRects(result)[0]!.width).toBe(80);
477+ expect(childRects(result)[0]!.x).toBe(0);
478+ });
479+
480+ test("center centers children on cross axis in VStack", () => {
481+ const node = VStack({ width: 80, height: 24, alignItems: "center" }, [
482+ VStack({ width: 20, height: 3 }, []),
483+ ]);
484+ const result = layout(node, 80, 24);
485+ // cross remaining = 80 - 20 = 60, offset = 30
486+ expect(childRects(result)[0]!.x).toBe(30);
487+ });
488+
489+ test("end aligns children to the end of cross axis", () => {
490+ const node = VStack({ width: 80, height: 24, alignItems: "end" }, [
491+ VStack({ width: 20, height: 3 }, []),
492+ ]);
493+ const result = layout(node, 80, 24);
494+ // cross remaining = 80 - 20 = 60
495+ expect(childRects(result)[0]!.x).toBe(60);
496+ });
497+
498+ test("start aligns children to the start of cross axis", () => {
499+ const node = VStack({ width: 80, height: 24, alignItems: "start" }, [
500+ VStack({ width: 20, height: 3 }, []),
501+ ]);
502+ const result = layout(node, 80, 24);
503+ expect(childRects(result)[0]!.x).toBe(0);
504+ });
505+
506+ test("center in HStack centers vertically", () => {
507+ const node = HStack({ width: 80, height: 24, alignItems: "center" }, [
508+ VStack({ width: 20, height: 6 }, []),
509+ ]);
510+ const result = layout(node, 80, 24);
511+ // cross = height, remaining = 24 - 6 = 18, offset = 9
512+ expect(childRects(result)[0]!.y).toBe(9);
513+ });
514+
515+ test("end in HStack pushes children to the bottom", () => {
516+ const node = HStack({ width: 80, height: 24, alignItems: "end" }, [
517+ VStack({ width: 20, height: 6 }, []),
518+ ]);
519+ const result = layout(node, 80, 24);
520+ expect(childRects(result)[0]!.y).toBe(18);
521+ });
522+
523+ test("alignItems with padding", () => {
524+ const node = VStack(
525+ {
526+ width: 80,
527+ height: 24,
528+ alignItems: "center",
529+ padding: { x: 5 },
530+ },
531+ [VStack({ width: 20, height: 3 }, [])],
532+ );
533+ const result = layout(node, 80, 24);
534+ // inner width = 80 - 10 = 70, remaining = 70 - 20 = 50, offset = 25
535+ // child x = padX + offset = 5 + 25 = 30
536+ expect(childRects(result)[0]!.x).toBe(30);
537+ });
538+
539+ test("alignItems affects each child independently", () => {
540+ const node = VStack({ width: 80, height: 24, alignItems: "center" }, [
541+ VStack({ width: 20, height: 3 }, []),
542+ VStack({ width: 40, height: 3 }, []),
543+ ]);
544+ const result = layout(node, 80, 24);
545+ const rects = childRects(result);
546+ // child 1: (80 - 20) / 2 = 30
547+ expect(rects[0]!.x).toBe(30);
548+ // child 2: (80 - 40) / 2 = 20
549+ expect(rects[1]!.x).toBe(20);
550+ });
551+
552+ test("center uses intrinsic cross size for Text children", () => {
553+ // Text("hello") has intrinsic width 5. With alignItems center,
554+ // it should be centered in 80 columns, not fill the width.
555+ const node = VStack({ width: 80, height: 24, alignItems: "center" }, [
556+ Text("hello"),
557+ ]);
558+ const result = layout(node, 80, 24);
559+ const r = childRects(result)[0]!;
560+ // intrinsic width of "hello" = 5, cross = 80
561+ // offset = (80 - 5) / 2 = 37 (floored from 37.5)
562+ expect(r.x).toBe(37);
563+ expect(r.width).toBe(5);
564+ });
565+
566+ test("center uses intrinsic cross size for HStack without explicit width", () => {
567+ const node = VStack({ width: 80, height: 24, alignItems: "center" }, [
568+ HStack({ gap: 1 }, [Text("aa"), Text("bb")]),
569+ ]);
570+ const result = layout(node, 80, 24);
571+ const r = childRects(result)[0]!;
572+ // HStack intrinsic width = 2 + 1 + 2 = 5
573+ expect(r.width).toBe(5);
574+ expect(r.x).toBe(37);
575+ });
576+
577+ test("end uses intrinsic cross size for children without explicit width", () => {
578+ const node = VStack({ width: 80, height: 24, alignItems: "end" }, [
579+ Text("hi"),
580+ ]);
581+ const result = layout(node, 80, 24);
582+ const r = childRects(result)[0]!;
583+ // intrinsic width of "hi" = 2
584+ expect(r.width).toBe(2);
585+ expect(r.x).toBe(78);
586+ });
587+
588+ test("stretch still fills cross axis (default)", () => {
589+ const node = VStack({ width: 80, height: 24, alignItems: "stretch" }, [
590+ Text("hi"),
591+ ]);
592+ const result = layout(node, 80, 24);
593+ expect(childRects(result)[0]!.width).toBe(80);
594+ expect(childRects(result)[0]!.x).toBe(0);
595+ });
596+
597+ test("combined justifyContent center + alignItems center", () => {
598+ const node = VStack(
599+ {
600+ width: 80,
601+ height: 24,
602+ justifyContent: "center",
603+ alignItems: "center",
604+ },
605+ [VStack({ width: 20, height: 4 }, [])],
606+ );
607+ const result = layout(node, 80, 24);
608+ const r = childRects(result)[0]!;
609+ // main (y): (24 - 4) / 2 = 10
610+ expect(r.y).toBe(10);
611+ // cross (x): (80 - 20) / 2 = 30
612+ expect(r.x).toBe(30);
613+ });
614+ });
615+
356616 describe("nested layout", () => {
357617 test("editor-like layout: sidebar + main area", () => {
358618 const node = HStack({ width: 80, height: 24 }, [
packages/core/src/layout.ts+69−10
@@ -251,6 +251,8 @@ function layoutNode(
251251 const infos: ChildInfo[] = [];
252252 let fixedMain = 0;
253253 let totalFlex = 0;
254+ const align = props.alignItems ?? "stretch";
255+ const useIntrinsicCross = align !== "stretch";
254256
255257 for (const child of children) {
256258 const cProps = getProps(child);
@@ -258,10 +260,19 @@ function layoutNode(
258260
259261 if (flex > 0) {
260262 totalFlex += flex;
261- // Cross-axis
262- const cross = isVertical
263- ? (resolveSizeValue(cProps?.width, innerW) ?? innerW)
264- : (resolveSizeValue(cProps?.height, innerH) ?? innerH);
263+ // Cross-axis: explicit size, or intrinsic if not stretch, or fill
264+ let cross: number;
265+ if (isVertical) {
266+ cross =
267+ resolveSizeValue(cProps?.width, innerW) ??
268+ (useIntrinsicCross
269+ ? intrinsicMainSize(child, false, innerH)
270+ : innerW);
271+ } else {
272+ cross =
273+ resolveSizeValue(cProps?.height, innerH) ??
274+ (useIntrinsicCross ? intrinsicMainSize(child, true, innerW) : innerH);
275+ }
265276 infos.push({ node: child, mainSize: 0, crossSize: cross, flex });
266277 } else {
267278 // Main-axis: explicit → percentage → intrinsic
@@ -271,12 +282,18 @@ function layoutNode(
271282 main =
272283 resolveSizeValue(cProps?.height, innerH) ??
273284 intrinsicMainSize(child, true, innerW);
274- cross = resolveSizeValue(cProps?.width, innerW) ?? innerW;
285+ cross =
286+ resolveSizeValue(cProps?.width, innerW) ??
287+ (useIntrinsicCross
288+ ? intrinsicMainSize(child, false, innerH)
289+ : innerW);
275290 } else {
276291 main =
277292 resolveSizeValue(cProps?.width, innerW) ??
278293 intrinsicMainSize(child, false, innerH);
279- cross = resolveSizeValue(cProps?.height, innerH) ?? innerH;
294+ cross =
295+ resolveSizeValue(cProps?.height, innerH) ??
296+ (useIntrinsicCross ? intrinsicMainSize(child, true, innerW) : innerH);
280297 }
281298
282299 // Apply constraints
@@ -320,20 +337,62 @@ function layoutNode(
320337 }
321338
322339 // --- Position phase ---
340+
341+ // Compute total main-axis content size (children + gaps)
342+ const totalChildMain = infos.reduce((sum, c) => sum + c.mainSize, 0);
343+ const totalContent = totalChildMain + totalGap;
344+ const mainInner = isVertical ? innerH : innerW;
345+ const crossInner = isVertical ? innerW : innerH;
346+ const remainingMain = Math.max(0, mainInner - totalContent);
347+
348+ // justifyContent: compute main-axis starting offset and per-gap extra space
349+ const justify = props.justifyContent ?? "start";
350+ let mainStart = 0;
351+ let betweenGaps: number[] | null = null;
352+
353+ if (justify === "end") {
354+ mainStart = remainingMain;
355+ } else if (justify === "center") {
356+ mainStart = Math.floor(remainingMain / 2);
357+ } else if (justify === "space-between" && infos.length > 1) {
358+ // Distribute remaining space into gaps between children
359+ const gapCount = infos.length - 1;
360+ const rawGaps = Array.from(
361+ { length: gapCount },
362+ () => remainingMain / gapCount,
363+ );
364+ betweenGaps = largestRemainder(rawGaps, remainingMain);
365+ }
366+
323367 const layoutChildren: LayoutNode[] = [];
324- let mainOffset = 0;
368+ let mainOffset = mainStart;
325369
326370 for (let i = 0; i < infos.length; i++) {
327371 const info = infos[i]!;
328- const childX = isVertical ? innerX : innerX + mainOffset;
329- const childY = isVertical ? innerY + mainOffset : innerY;
372+
373+ // Cross-axis alignment
374+ let crossOffset = 0;
375+ if (align === "center") {
376+ crossOffset = Math.floor((crossInner - info.crossSize) / 2);
377+ } else if (align === "end") {
378+ crossOffset = crossInner - info.crossSize;
379+ }
380+ // "start" and "stretch" keep crossOffset = 0
381+
382+ const childX = isVertical ? innerX + crossOffset : innerX + mainOffset;
383+ const childY = isVertical ? innerY + mainOffset : innerY + crossOffset;
330384 const childW = isVertical ? info.crossSize : info.mainSize;
331385 const childH = isVertical ? info.mainSize : info.crossSize;
332386
333387 layoutChildren.push(layoutNode(info.node, childX, childY, childW, childH));
334388
335389 mainOffset += info.mainSize;
336- if (i < infos.length - 1) mainOffset += gap;
390+ if (i < infos.length - 1) {
391+ mainOffset += gap;
392+ if (betweenGaps) {
393+ mainOffset += betweenGaps[i]!;
394+ }
395+ }
337396 }
338397
339398 // --- Intrinsic container sizing ---