@@ -648,6 +648,447 @@ describe("layout", () => {
648648 });
649649 });
650650
651+ describe("flexWrap", () => {
652+ test("nowrap is the default — children stay on one line", () => {
653+ // Three 30-wide children in an 80-wide HStack: total 90, no wrapping
654+ const node = HStack({ width: 80, height: 24 }, [
655+ VStack({ width: 30, height: 5 }, []),
656+ VStack({ width: 30, height: 5 }, []),
657+ VStack({ width: 30, height: 5 }, []),
658+ ]);
659+ const result = layout(node, 80, 24);
660+ const rects = childRects(result);
661+ // All on same row (y=0), positioned left-to-right
662+ expect(rects[0]!.y).toBe(0);
663+ expect(rects[1]!.y).toBe(0);
664+ expect(rects[2]!.y).toBe(0);
665+ expect(rects[0]!.x).toBe(0);
666+ expect(rects[1]!.x).toBe(30);
667+ expect(rects[2]!.x).toBe(60);
668+ });
669+
670+ test("wrap splits children into rows when they exceed width", () => {
671+ // Three 30-wide children in an 80-wide HStack with wrap
672+ // Row 1: child0 (30) + child1 (30) = 60 ≤ 80 ✓
673+ // Row 2: child2 (30) — adding to row 1 would be 90 > 80
674+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, [
675+ VStack({ width: 30, height: 5 }, []),
676+ VStack({ width: 30, height: 5 }, []),
677+ VStack({ width: 30, height: 5 }, []),
678+ ]);
679+ const result = layout(node, 80, 24);
680+ const rects = childRects(result);
681+ // Row 1: child0 at (0,0), child1 at (30,0)
682+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 30, height: 5 });
683+ expect(rects[1]).toEqual({ x: 30, y: 0, width: 30, height: 5 });
684+ // Row 2: child2 at (0,5)
685+ expect(rects[2]).toEqual({ x: 0, y: 5, width: 30, height: 5 });
686+ });
687+
688+ test("all children fit on one row — no wrapping", () => {
689+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, [
690+ VStack({ width: 20, height: 3 }, []),
691+ VStack({ width: 20, height: 3 }, []),
692+ VStack({ width: 20, height: 3 }, []),
693+ ]);
694+ const result = layout(node, 80, 24);
695+ const rects = childRects(result);
696+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 20, height: 3 });
697+ expect(rects[1]).toEqual({ x: 20, y: 0, width: 20, height: 3 });
698+ expect(rects[2]).toEqual({ x: 40, y: 0, width: 20, height: 3 });
699+ });
700+
701+ test("each child on its own row when each exceeds half the width", () => {
702+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, [
703+ VStack({ width: 50, height: 2 }, []),
704+ VStack({ width: 50, height: 3 }, []),
705+ VStack({ width: 50, height: 4 }, []),
706+ ]);
707+ const result = layout(node, 80, 24);
708+ const rects = childRects(result);
709+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 50, height: 2 });
710+ expect(rects[1]).toEqual({ x: 0, y: 2, width: 50, height: 3 });
711+ expect(rects[2]).toEqual({ x: 0, y: 5, width: 50, height: 4 });
712+ });
713+
714+ test("row height is the max cross-size of children in that row", () => {
715+ // Row 1: height-2 and height-5 → row height 5
716+ // Row 2: height-3 → row height 3
717+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, [
718+ VStack({ width: 50, height: 2 }, []),
719+ VStack({ width: 20, height: 5 }, []),
720+ VStack({ width: 50, height: 3 }, []),
721+ ]);
722+ const result = layout(node, 80, 24);
723+ const rects = childRects(result);
724+ // Row 1: both at y=0, row height = max(2,5) = 5
725+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 50, height: 2 });
726+ expect(rects[1]).toEqual({ x: 50, y: 0, width: 20, height: 5 });
727+ // Row 2: starts at y=5
728+ expect(rects[2]).toEqual({ x: 0, y: 5, width: 50, height: 3 });
729+ });
730+
731+ test("gap between items within a row", () => {
732+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap", gap: 2 }, [
733+ VStack({ width: 30, height: 3 }, []),
734+ VStack({ width: 30, height: 3 }, []),
735+ VStack({ width: 30, height: 3 }, []),
736+ ]);
737+ const result = layout(node, 80, 24);
738+ const rects = childRects(result);
739+ // Row 1: child0(30) + gap(2) + child1(30) = 62 ≤ 80 ✓
740+ // + gap(2) + child2(30) = 94 > 80 ✗
741+ // Row 2: child2
742+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 30, height: 3 });
743+ expect(rects[1]).toEqual({ x: 32, y: 0, width: 30, height: 3 });
744+ // Row 2 starts at y = row1Height(3) + gap(2) = 5
745+ expect(rects[2]).toEqual({ x: 0, y: 5, width: 30, height: 3 });
746+ });
747+
748+ test("gap between rows", () => {
749+ // Every child gets its own row, gap between rows
750+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap", gap: 1 }, [
751+ VStack({ width: 80, height: 2 }, []),
752+ VStack({ width: 80, height: 3 }, []),
753+ ]);
754+ const result = layout(node, 80, 24);
755+ const rects = childRects(result);
756+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 80, height: 2 });
757+ // gap between rows = 1
758+ expect(rects[1]).toEqual({ x: 0, y: 3, width: 80, height: 3 });
759+ });
760+
761+ test("flex children distribute remaining space within their row", () => {
762+ // Row 1: fixed(20) + flex(1) → flex gets 80-20 = 60
763+ // Row 2: flex(1) → flex gets 80
764+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, [
765+ VStack({ width: 20, height: 3 }, []),
766+ VStack({ flex: 1, height: 3 }, []),
767+ VStack({ width: 90, height: 4 }, []), // wider than container, own row
768+ ]);
769+ const result = layout(node, 80, 24);
770+ const rects = childRects(result);
771+ // Row 1: fixed + flex
772+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 20, height: 3 });
773+ expect(rects[1]).toEqual({ x: 20, y: 0, width: 60, height: 3 });
774+ // Row 2: child wider than container
775+ expect(rects[2]!.y).toBe(3);
776+ });
777+
778+ test("multiple flex children in one row share space", () => {
779+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, [
780+ VStack({ width: 20, height: 3 }, []),
781+ VStack({ flex: 1, height: 3 }, []),
782+ VStack({ flex: 1, height: 3 }, []),
783+ ]);
784+ const result = layout(node, 80, 24);
785+ const rects = childRects(result);
786+ // All fit in one row. Remaining = 80 - 20 = 60, split 30/30
787+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 20, height: 3 });
788+ expect(rects[1]).toEqual({ x: 20, y: 0, width: 30, height: 3 });
789+ expect(rects[2]).toEqual({ x: 50, y: 0, width: 30, height: 3 });
790+ });
791+
792+ test("padding reduces available width for wrapping", () => {
793+ // Inner width = 80 - 2*5 = 70
794+ // Row 1: 40 ≤ 70 ✓, 40+40=80 > 70 ✗
795+ // Row 2: 40
796+ const node = HStack(
797+ { width: 80, height: 24, flexWrap: "wrap", padding: { x: 5, y: 2 } },
798+ [
799+ VStack({ width: 40, height: 3 }, []),
800+ VStack({ width: 40, height: 3 }, []),
801+ ],
802+ );
803+ const result = layout(node, 80, 24);
804+ const rects = childRects(result);
805+ // Row 1 at padded origin
806+ expect(rects[0]).toEqual({ x: 5, y: 2, width: 40, height: 3 });
807+ // Row 2
808+ expect(rects[1]).toEqual({ x: 5, y: 5, width: 40, height: 3 });
809+ });
810+
811+ test("alignItems stretch makes children fill row height", () => {
812+ // Default alignItems is stretch. Children should fill their row's height.
813+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, [
814+ VStack({ width: 50, height: 2 }, []),
815+ VStack({ width: 20 }, []), // no explicit height
816+ VStack({ width: 50, height: 3 }, []),
817+ ]);
818+ const result = layout(node, 80, 24);
819+ const rects = childRects(result);
820+ // Row 1: max height = 2 (first child), second child stretches to 2
821+ // But wait — when the second child has no explicit height, under stretch
822+ // it should fill the row height, which is determined by the tallest child.
823+ // The tallest in row 1 is 2, so stretched child gets 2.
824+ expect(rects[0]!.height).toBe(2);
825+ expect(rects[1]!.height).toBe(2);
826+ // Row 2
827+ expect(rects[2]!.height).toBe(3);
828+ });
829+
830+ test("alignItems center centers children vertically within row", () => {
831+ const node = HStack(
832+ { width: 80, height: 24, flexWrap: "wrap", alignItems: "center" },
833+ [
834+ VStack({ width: 50, height: 6 }, []),
835+ VStack({ width: 20, height: 2 }, []),
836+ ],
837+ );
838+ const result = layout(node, 80, 24);
839+ const rects = childRects(result);
840+ // Single row, row height = 6
841+ // First child: y=0, height=6 (fills row)
842+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 50, height: 6 });
843+ // Second child: centered in 6-high row → (6-2)/2 = 2
844+ expect(rects[1]).toEqual({ x: 50, y: 2, width: 20, height: 2 });
845+ });
846+
847+ test("alignItems end aligns children to bottom of row", () => {
848+ const node = HStack(
849+ { width: 80, height: 24, flexWrap: "wrap", alignItems: "end" },
850+ [
851+ VStack({ width: 50, height: 6 }, []),
852+ VStack({ width: 20, height: 2 }, []),
853+ ],
854+ );
855+ const result = layout(node, 80, 24);
856+ const rects = childRects(result);
857+ // Row height = 6. Second child at bottom: y = 6-2 = 4
858+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 50, height: 6 });
859+ expect(rects[1]).toEqual({ x: 50, y: 4, width: 20, height: 2 });
860+ });
861+
862+ test("justifyContent center centers items within each row", () => {
863+ const node = HStack(
864+ { width: 80, height: 24, flexWrap: "wrap", justifyContent: "center" },
865+ [
866+ VStack({ width: 30, height: 3 }, []),
867+ VStack({ width: 30, height: 3 }, []),
868+ VStack({ width: 30, height: 3 }, []),
869+ ],
870+ );
871+ const result = layout(node, 80, 24);
872+ const rects = childRects(result);
873+ // Row 1: child0+child1 = 60, remaining = 20, offset = 10
874+ expect(rects[0]).toEqual({ x: 10, y: 0, width: 30, height: 3 });
875+ expect(rects[1]).toEqual({ x: 40, y: 0, width: 30, height: 3 });
876+ // Row 2: child2 = 30, remaining = 50, offset = 25
877+ expect(rects[2]).toEqual({ x: 25, y: 3, width: 30, height: 3 });
878+ });
879+
880+ test("justifyContent end pushes items to end of each row", () => {
881+ const node = HStack(
882+ { width: 80, height: 24, flexWrap: "wrap", justifyContent: "end" },
883+ [
884+ VStack({ width: 30, height: 3 }, []),
885+ VStack({ width: 30, height: 3 }, []),
886+ VStack({ width: 30, height: 3 }, []),
887+ ],
888+ );
889+ const result = layout(node, 80, 24);
890+ const rects = childRects(result);
891+ // Row 1: 30+30 = 60, remaining = 20, offset = 20
892+ expect(rects[0]).toEqual({ x: 20, y: 0, width: 30, height: 3 });
893+ expect(rects[1]).toEqual({ x: 50, y: 0, width: 30, height: 3 });
894+ // Row 2: 30, remaining = 50, offset = 50
895+ expect(rects[2]).toEqual({ x: 50, y: 3, width: 30, height: 3 });
896+ });
897+
898+ test("justifyContent space-between distributes within each row", () => {
899+ const node = HStack(
900+ {
901+ width: 80,
902+ height: 24,
903+ flexWrap: "wrap",
904+ justifyContent: "space-between",
905+ },
906+ [
907+ VStack({ width: 20, height: 3 }, []),
908+ VStack({ width: 20, height: 3 }, []),
909+ VStack({ width: 20, height: 3 }, []),
910+ VStack({ width: 20, height: 3 }, []),
911+ ],
912+ );
913+ const result = layout(node, 80, 24);
914+ const rects = childRects(result);
915+ // All 4 fit: 20*4 = 80 — no wrapping needed
916+ // Remaining = 0 with space-between
917+ expect(rects[0]!.x).toBe(0);
918+ expect(rects[1]!.x).toBe(20);
919+ expect(rects[2]!.x).toBe(40);
920+ expect(rects[3]!.x).toBe(60);
921+ });
922+
923+ test("intrinsic height of wrapping HStack equals sum of row heights", () => {
924+ // HStack with no explicit height should size to fit all rows
925+ const node = VStack({ width: 80, height: 24 }, [
926+ HStack({ flexWrap: "wrap" }, [
927+ VStack({ width: 50, height: 3 }, []),
928+ VStack({ width: 50, height: 4 }, []),
929+ ]),
930+ Text("below"),
931+ ]);
932+ const result = layout(node, 80, 24);
933+ const rects = childRects(result);
934+ // HStack: row1 height=3, row2 height=4, total = 7
935+ expect(rects[0]!.height).toBe(7);
936+ // Text below starts at y=7
937+ expect(rects[1]!.y).toBe(7);
938+ });
939+
940+ test("intrinsic height with gap includes gaps between rows", () => {
941+ const node = VStack({ width: 80, height: 24 }, [
942+ HStack({ flexWrap: "wrap", gap: 1 }, [
943+ VStack({ width: 80, height: 2 }, []),
944+ VStack({ width: 80, height: 3 }, []),
945+ ]),
946+ Text("below"),
947+ ]);
948+ const result = layout(node, 80, 24);
949+ const rects = childRects(result);
950+ // Two rows: 2 + gap(1) + 3 = 6
951+ expect(rects[0]!.height).toBe(6);
952+ expect(rects[1]!.y).toBe(6);
953+ });
954+
955+ test("Text children wrap based on intrinsic width", () => {
956+ // Text nodes have intrinsic width. They should wrap like other nodes.
957+ const node = HStack({ width: 20, height: 10, flexWrap: "wrap" }, [
958+ Text("hello"), // width 5
959+ Text("world"), // width 5
960+ Text("this is long text"), // width 17
961+ ]);
962+ const result = layout(node, 20, 10);
963+ const rects = childRects(result);
964+ // Row 1: "hello"(5) + "world"(5) = 10 ≤ 20 ✓
965+ // + "this is long text"(17) = 27 > 20 ✗
966+ // Row 2: "this is long text"
967+ expect(rects[0]!.y).toBe(0);
968+ expect(rects[1]!.y).toBe(0);
969+ expect(rects[2]!.y).toBe(1); // second row
970+ expect(rects[0]!.x).toBe(0);
971+ expect(rects[1]!.x).toBe(5);
972+ expect(rects[2]!.x).toBe(0);
973+ });
974+
975+ test("single child wider than container gets its own row", () => {
976+ const node = HStack({ width: 40, height: 24, flexWrap: "wrap" }, [
977+ VStack({ width: 20, height: 3 }, []),
978+ VStack({ width: 50, height: 4 }, []), // wider than container
979+ VStack({ width: 20, height: 2 }, []),
980+ ]);
981+ const result = layout(node, 40, 24);
982+ const rects = childRects(result);
983+ // Row 1: child0 (20 ≤ 40)
984+ // child1 (20+50 > 40, starts new row)
985+ // Row 2: child1 (50 > 40, but it's the first item so it goes on this row)
986+ // Row 3: child2 (50+20 > 40, new row)
987+ expect(rects[0]!.y).toBe(0);
988+ expect(rects[1]!.y).toBe(3); // after row 1 (height 3)
989+ expect(rects[2]!.y).toBe(7); // after row 2 (height 4)
990+ });
991+
992+ test("empty HStack with flexWrap produces no children", () => {
993+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, []);
994+ const result = layout(node, 80, 24);
995+ expect(result.children).toEqual([]);
996+ });
997+
998+ test("single child in wrapping HStack", () => {
999+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, [
1000+ VStack({ width: 30, height: 5 }, []),
1001+ ]);
1002+ const result = layout(node, 80, 24);
1003+ const rects = childRects(result);
1004+ expect(rects[0]).toEqual({ x: 0, y: 0, width: 30, height: 5 });
1005+ });
1006+
1007+ test("flexWrap on VStack is ignored (treated as nowrap)", () => {
1008+ // flexWrap is only meaningful on HStack per the spec
1009+ const node = VStack({ width: 80, height: 10, flexWrap: "wrap" as any }, [
1010+ VStack({ height: 4 }, []),
1011+ VStack({ height: 4 }, []),
1012+ VStack({ height: 4 }, []),
1013+ ]);
1014+ const result = layout(node, 80, 10);
1015+ const rects = childRects(result);
1016+ // Normal VStack behavior — children stack vertically, overflow
1017+ expect(rects[0]!.y).toBe(0);
1018+ expect(rects[1]!.y).toBe(4);
1019+ expect(rects[2]!.y).toBe(8);
1020+ });
1021+
1022+ test("nested wrapping HStack inside VStack", () => {
1023+ const node = VStack({ width: 60, height: 24 }, [
1024+ Text("Title"),
1025+ HStack({ flexWrap: "wrap", gap: 1 }, [
1026+ VStack({ width: 25, height: 2 }, []),
1027+ VStack({ width: 25, height: 2 }, []),
1028+ VStack({ width: 25, height: 2 }, []),
1029+ ]),
1030+ Text("Footer"),
1031+ ]);
1032+ const result = layout(node, 60, 24);
1033+ const rects = childRects(result);
1034+
1035+ // Title at y=0, height=1
1036+ expect(rects[0]!.y).toBe(0);
1037+ expect(rects[0]!.height).toBe(1);
1038+
1039+ // HStack at y=1
1040+ // Row 1: 25 + 1 + 25 = 51 ≤ 60, + 1 + 25 = 77 > 60
1041+ // Row 2: 25
1042+ // HStack height = 2 + 1 + 2 = 5
1043+ expect(rects[1]!.y).toBe(1);
1044+ expect(rects[1]!.height).toBe(5);
1045+
1046+ // Footer at y=6
1047+ expect(rects[2]!.y).toBe(6);
1048+
1049+ // Verify HStack's children
1050+ const hstackChildren = result.children[1]!.children;
1051+ expect(hstackChildren[0]!.rect).toEqual({
1052+ x: 0,
1053+ y: 1,
1054+ width: 25,
1055+ height: 2,
1056+ });
1057+ expect(hstackChildren[1]!.rect).toEqual({
1058+ x: 26,
1059+ y: 1,
1060+ width: 25,
1061+ height: 2,
1062+ });
1063+ expect(hstackChildren[2]!.rect).toEqual({
1064+ x: 0,
1065+ y: 4,
1066+ width: 25,
1067+ height: 2,
1068+ });
1069+ });
1070+
1071+ test("constraints apply to children in wrapped rows", () => {
1072+ const node = HStack({ width: 80, height: 24, flexWrap: "wrap" }, [
1073+ VStack({ flex: 1, minWidth: 30, height: 3 }, []),
1074+ VStack({ flex: 1, minWidth: 30, height: 3 }, []),
1075+ VStack({ flex: 1, minWidth: 30, height: 3 }, []),
1076+ ]);
1077+ const result = layout(node, 80, 24);
1078+ const rects = childRects(result);
1079+ // Flex children: need to decide row membership based on min sizes
1080+ // Each has minWidth 30. Three at 30 = 90 > 80, so wrapping occurs.
1081+ // Row 1: child0 + child1 at minWidth 30 each = 60 ≤ 80
1082+ // Remaining = 80 - 0 (no fixed) = 80, shared between 2 flex → 40 each
1083+ // Both ≥ 30 ✓
1084+ // Row 2: child2 → gets full 80
1085+ expect(rects[0]!.width).toBe(40);
1086+ expect(rects[1]!.width).toBe(40);
1087+ expect(rects[2]!.y).toBe(3);
1088+ expect(rects[2]!.width).toBe(80);
1089+ });
1090+ });
1091+
6511092 describe("nested layout", () => {
6521093 test("editor-like layout: sidebar + main area", () => {
6531094 const node = HStack({ width: 80, height: 24 }, [