# packages/core/src/lib/layout/flex.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/lib/layout/flex.ts#L203). [Back to reference](/reference/components/flex/)
1 import { preparedStyleValue, preparedStyleQuery, type PreparedQuery } from '../style/responsive.js';
2 import { definePrimitive } from '../define-primitive.js';
3 import { clonePibblElement } from '../element/create-element.js';
4 import { getChildPrimitiveReceiverToken } from '../element/metadata.js';
5 import type { PibblElement } from '../element/types.js';
6 import { GLOBAL_STATE } from '../global-state.js';
7 import { layoutDiagnostic } from '../style/diagnostics.js';
8 import {
9   type PibblStructuralEventProps,
10   wireStructuralEvents,
11 } from '../components/structural-events.js';
12 import { normalizeEdges } from '../style/normalize.js';
13 import { resolveLength } from '../style/resolve-length.js';
14 import { setPreNormalizedStyle } from '../style/resolve-dispatch.js';
15 import type {
16   BoxStyle,
17   FlexItemStyle,
18   LayoutItemStyle,
19   ResolvedBoxStyle,
20 } from '../style/types.js';
21 import type {
22   CanvasMeasurementService,
23   PibblNodeInput,
24   MeasureInput,
25   MeasureResult,
26   RenderingContext2D,
27   SystemStyle,
28 } from '../types.js';
29 import {
30   childWithUsedSize,
31   prepareDirectChildStyle,
32   materializeLayoutChildren,
33   placeDirectChildren,
34   prepareLayoutChildren,
35   resolveContainerBox,
36 } from './absolute.js';
37 import { pushLayoutBox } from './context.js';
38 import { recordLayoutEvaluation } from './diagnostics.js';
39 import { assertSupportedChildPosition } from './positioning-diagnostics.js';
40 import { measureElement } from './measure.js';
41 import type { Constraints, LayoutBox } from './types.js';
42 
43 type FlexDirection = 'row' | 'column';
44 type FlexWrap = 'nowrap' | 'wrap';
45 type MainAlignment =
46   | 'flex-start'
47   | 'flex-end'
48   | 'center'
49   | 'space-between'
50   | 'space-around'
51   | 'space-evenly';
52 type CrossAlignment = 'stretch' | 'flex-start' | 'flex-end' | 'center';
53 
54 /**
55  * Supported geometry and presentation properties for Flex.
56  *
57  * @see {@link BoxStyle}
58  * @see {@link LayoutItemStyle}
59  * @see {@link Flex}
60  */
61 export interface FlexStyle extends BoxStyle, LayoutItemStyle {
62   /** The main axis along which flex children are placed. See {@link FlexDirection}. */
63   flexDirection?: FlexDirection;
64   /** Whether children may wrap onto additional flex lines. See {@link FlexWrap}. */
65   flexWrap?: FlexWrap;
66   /** Distribution of children along the main axis. See {@link MainAlignment}. */
67   justifyContent?: MainAlignment;
68   /** Default alignment of children on the cross or block axis. See {@link CrossAlignment}. */
69   alignItems?: CrossAlignment;
70   /**
71    * Distribution of wrapped flex lines within the available cross-axis space. See
72    * {@link CrossAlignment}, {@link MainAlignment}.
73    */
74   alignContent?: CrossAlignment | MainAlignment;
75   /** Spacing between adjacent items. See {@link FlexStyle}. */
76   gap?: number;
77   /** Space between adjacent rows or items on the row axis. See {@link FlexStyle}. */
78   rowGap?: number;
79   /** Space between adjacent columns or items on the column axis. See {@link FlexStyle}. */
80   columnGap?: number;
81 }
82 
83 /**
84  * Authored inputs for Flex, including the declared data and presentation options.
85  *
86  * @see {@link PibblNodeInput}
87  * @see {@link Flex}
88  */
89 export interface FlexProps extends PibblStructuralEventProps {
90   /** Descendant content or the callback that supplies it. See {@link PibblNodeInput}. */
91   children: PibblNodeInput;
92 }
93 
94 export interface FlexMeasurementInput {
95   service: CanvasMeasurementService;
96   measureElement(
97     element: PibblElement<any>,
98     constraints: Readonly<Constraints>,
99   ): MeasureResult;
100 }
101 
102 interface ResolvedFlexStyle extends SystemStyle {
103   box: ResolvedBoxStyle;
104   overflow: 'visible' | 'clip';
105   flexDirection: FlexDirection;
106   flexWrap: FlexWrap;
107   justifyContent: MainAlignment;
108   alignItems: CrossAlignment;
109   alignContent: CrossAlignment | MainAlignment;
110   rowGap: number;
111   columnGap: number;
112 }
113 
114 interface FlexItem {
115   child: PibblElement<any>;
116   normalized: Readonly<BoxStyle & FlexItemStyle & LayoutItemStyle>;
117   baseMain: number;
118   targetMain: number;
119   paddingMain: number;
120   preferredCross: number;
121   paddingCross: number;
122   minMain: number;
123   maxMain: number;
124   minCross: number;
125   maxCross: number;
126   grow: number;
127   shrink: number;
128   crossAuto: boolean;
129   alignSelf: CrossAlignment | 'auto';
130   receiverToken: object;
131   query?: PreparedQuery;
132 }
133 
134 interface FlexLine {
135   items: FlexItem[];
136   crossSize: number;
137   crossOffset: number;
138 }
139 
140 interface FlexPlacement {
141   box: LayoutBox;
142   element: PibblElement<any>;
143 }
144 
145 function renderFlex(
146   props: FlexProps,
147   style: Readonly<ResolvedFlexStyle>,
148   ctx: RenderingContext2D,
149 ) {
150   wireStructuralEvents(props);
151   const children = prepareLayoutChildren(props.children, 'Flex');
152   recordLayoutEvaluation();
153   const content = style.box.contentBox;
154   ctx.translate(content.x, content.y);
155   const localContent = Object.freeze({
156     x: 0,
157     y: 0,
158     width: content.width,
159     height: content.height,
160   });
161   const releaseLayout = pushLayoutBox(localContent);
162   GLOBAL_STATE.componentRefs!.onAfterRender = releaseLayout;
163   const service = {
164     measureText(value: string, font: string) {
165       ctx.save();
166       try {
167         ctx.font = font;
168         return ctx.measureText(value);
169       } finally {
170         ctx.restore();
171       }
172     },
173   };
174   const placements = resolveFlexPlacements(
175     localContent,
176     children,
177     style,
178     {
179       service,
180       measureElement: (element, constraints) =>
181         measureElement(element, constraints, service),
182     },
183   );
184   let index = 0;
185   return placeDirectChildren(
186     children,
187     localContent,
188     () => placements[index++],
189     style.overflow,
190   );
191 }
192 
193 /**
194  * Describes the supported Flexbox subset for JSX or createElement authoring.
195  *
196  * @param props - Authored component inputs, supplied through JSX or createElement. See the linked
197  * props and style types.
198  * @throws When called directly; Pibbl mounts this component through JSX or createElement.
199  *
200  * @see {@link FlexProps}
201  * @see {@link FlexStyle}
202  */
203 export const Flex = definePrimitive<
204   FlexProps,
205   FlexStyle,
206   FlexStyle,
207   ResolvedFlexStyle
208 >(renderFlex, {
209   childInput: 'structural',
210   resolveStyle: (style, context) => ({
211     box: resolveContainerBox(style, context, 'Flex', 'flex'),
212     overflow: style.overflow ?? 'visible',
213     ...normalizeFlexOptions(style, context.allocation),
214   }),
215   measure: input => measureFlex(input),
216 });
217 
218 function measureFlex(
219   input: MeasureInput<FlexProps, FlexStyle>,
220 ): MeasureResult {
221   const children = prepareLayoutChildren(input.props.children, 'Flex');
222   const widthDefinite = input.style.width !== undefined &&
223     input.style.width !== 'auto';
224   const heightDefinite = input.style.height !== undefined &&
225     input.style.height !== 'auto';
226   if (widthDefinite && heightDefinite) {
227     return { status: 'measured', size: {
228       width: resolveMeasuredContainerLength(
229         input.style.width!,
230         input.constraints.maxWidth,
231         'width',
232         input.constraints,
233       ),
234       height: resolveMeasuredContainerLength(
235         input.style.height!,
236         input.constraints.maxHeight,
237         'height',
238         input.constraints,
239       ),
240     } };
241   }
242   if ((input.style.flexWrap ?? 'nowrap') !== 'nowrap') {
243     return unsupportedIntrinsic('requires nowrap because wrapped intrinsic sizing is deferred');
244   }
245   const row = (input.style.flexDirection ?? 'row') === 'row';
246   const diagnosticBox = {
247     x: 0,
248     y: 0,
249     width: Number.isFinite(input.constraints.maxWidth) ?
250       input.constraints.maxWidth : 0,
251     height: Number.isFinite(input.constraints.maxHeight) ?
252       input.constraints.maxHeight : 0,
253   };
254   const options = normalizeFlexOptions(input.style, diagnosticBox);
255   const mainGap = row ? options.columnGap : options.rowGap;
256   let intrinsicMain = 0;
257   let intrinsicCross = 0;
258   let count = 0;
259   for (const child of children) {
260     const receiverToken = getChildPrimitiveReceiverToken(
261       GLOBAL_STATE.renderTransaction,
262       GLOBAL_STATE.primitiveReceiverToken,
263       count,
264     );
265     const prepared = prepareDirectChildStyle(child, receiverToken, diagnosticBox);
266     const style = preparedStyleValue(prepared) as Readonly<
267       BoxStyle & FlexItemStyle & LayoutItemStyle & Record<string, unknown>
268     >;
269     rejectUnsupportedItemFields(child, style, diagnosticBox);
270     const grow = nonnegativeFactor(
271       style.flexGrow ?? 0,
272       'flexGrow',
273       child,
274       diagnosticBox,
275     );
276     if (grow !== 0) {
277       return unsupportedIntrinsic('does not support flexGrow during intrinsic measurement');
278     }
279     const shrink = nonnegativeFactor(
280       style.flexShrink ?? 1,
281       'flexShrink',
282       child,
283       diagnosticBox,
284     );
285     const basis = style.flexBasis ?? 'auto';
286     const mainProperty = row ? 'width' : 'height';
287     const crossProperty = row ? 'height' : 'width';
288     const minimumProperty = row ? 'minWidth' : 'minHeight';
289     if ((shrink > 0 || basis === 'auto') && style[minimumProperty] === undefined) {
290       throw childDiagnostic(
291         child,
292         minimumProperty,
293         style[minimumProperty],
294         diagnosticBox,
295         'an explicit main-axis minimum is required for shrink or auto basis',
296       );
297     }
298     const mainValue = basis === 'auto' ? style[mainProperty] : basis;
299     const crossValue = style[crossProperty];
300     if (isPercentage(mainValue) || isPercentage(crossValue) ||
301       hasPercentageBounds(style)) {
302       return unsupportedIntrinsic('does not support percentage child sizes or bounds');
303     }
304     if (mainValue === undefined || mainValue === 'auto') {
305       return unsupportedIntrinsic('requires a definite child basis; measured auto basis is deferred');
306     }
307     if (crossValue === undefined || crossValue === 'auto') {
308       return unsupportedIntrinsic('requires a definite child cross size');
309     }
310     const baseMain = intrinsicNumber(mainValue, 'flexBasis');
311     const baseCross = intrinsicNumber(crossValue, crossProperty);
312     const minMain = intrinsicOptionalNumber(style[minimumProperty], 0, minimumProperty);
313     const maxMainProperty = row ? 'maxWidth' : 'maxHeight';
314     const maxMain = intrinsicOptionalNumber(
315       style[maxMainProperty],
316       Number.POSITIVE_INFINITY,
317       maxMainProperty,
318     );
319     const minCrossProperty = row ? 'minHeight' : 'minWidth';
320     const maxCrossProperty = row ? 'maxHeight' : 'maxWidth';
321     const minCross = intrinsicOptionalNumber(style[minCrossProperty], 0, minCrossProperty);
322     const maxCross = intrinsicOptionalNumber(
323       style[maxCrossProperty],
324       Number.POSITIVE_INFINITY,
325       maxCrossProperty,
326     );
327     const padding = normalizeEdges(
328       style.padding,
329       'padding',
330       childContext(child, diagnosticBox),
331     );
332     const paddingMain = row ? padding.left + padding.right :
333       padding.top + padding.bottom;
334     const paddingCross = row ? padding.top + padding.bottom :
335       padding.left + padding.right;
336     intrinsicMain += clamp(baseMain, minMain, maxMain) + paddingMain;
337     intrinsicCross = Math.max(
338       intrinsicCross,
339       clamp(baseCross, minCross, maxCross) + paddingCross,
340     );
341     count++;
342   }
343   intrinsicMain += Math.max(0, count - 1) * mainGap;
344   return { status: 'measured', size: {
345     width: widthDefinite ? resolveMeasuredContainerLength(
346       input.style.width!,
347       input.constraints.maxWidth,
348       'width',
349       input.constraints,
350     ) : row ? intrinsicMain : intrinsicCross,
351     height: heightDefinite ? resolveMeasuredContainerLength(
352       input.style.height!,
353       input.constraints.maxHeight,
354       'height',
355       input.constraints,
356     ) : row ? intrinsicCross : intrinsicMain,
357   } };
358 }
359 
360 function resolveMeasuredContainerLength(
361   value: Exclude<BoxStyle['width'], undefined>,
362   reference: number,
363   property: string,
364   constraints: Readonly<Constraints>,
365 ): number {
366   const resolved = resolveLength(value, reference, property, {
367     component: 'Flex',
368     algorithm: 'measurement',
369     constraints,
370   });
371   if (resolved === undefined || resolved < 0) {
372     throw layoutDiagnostic({
373       component: 'Flex',
374       property,
375       value,
376       algorithm: 'measurement',
377       constraints,
378       reason: 'requires a definite nonnegative container size',
379     });
380   }
381   return resolved;
382 }
383 
384 function intrinsicNumber(
385   value: unknown,
386   property: string,
387 ): number {
388   if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
389     throw layoutDiagnostic({
390       component: 'Flex',
391       property,
392       value,
393       algorithm: 'measurement',
394       reason: 'intrinsic measurement requires finite nonnegative numeric sizes',
395     });
396   }
397   return value;
398 }
399 
400 function intrinsicOptionalNumber(
401   value: unknown,
402   fallback: number,
403   property: string,
404 ): number {
405   return value === undefined ? fallback : intrinsicNumber(value, property);
406 }
407 
408 function isPercentage(value: unknown): boolean {
409   return typeof value === 'string' && value.endsWith('%');
410 }
411 
412 function hasPercentageBounds(style: Readonly<BoxStyle>): boolean {
413   return [
414     style.minWidth,
415     style.maxWidth,
416     style.minHeight,
417     style.maxHeight,
418   ].some(isPercentage);
419 }
420 
421 function unsupportedIntrinsic(reason: string): MeasureResult {
422   return {
423     status: 'unsupported',
424     reason: `Flex intrinsic measurement ${reason}`,
425   };
426 }
427 
428 export function layoutFlex(
429   container: Readonly<LayoutBox>,
430   children: PibblNodeInput,
431   style: Readonly<FlexStyle>,
432   measurement: FlexMeasurementInput,
433 ): LayoutBox[] {
434   const prepared = materializeLayoutChildren(children, 'Flex');
435   return resolveFlexPlacements(container, prepared, style, measurement)
436     .map(placement => placement.box);
437 }
438 
439 function resolveFlexPlacements(
440   container: Readonly<LayoutBox>,
441   children: readonly PibblElement<any>[],
442   style: Readonly<FlexStyle>,
443   measurement: FlexMeasurementInput,
444 ): FlexPlacement[] {
445   assertFiniteBox(container);
446   const options = normalizeFlexOptions(style, container);
447   const row = options.flexDirection === 'row';
448   const mainSize = row ? container.width : container.height;
449   const crossSize = row ? container.height : container.width;
450   const mainGap = row ? options.columnGap : options.rowGap;
451   const crossGap = row ? options.rowGap : options.columnGap;
452   const items: FlexItem[] = [];
453 
454   for (const child of children) {
455     const receiverToken = getChildPrimitiveReceiverToken(
456       GLOBAL_STATE.renderTransaction,
457       GLOBAL_STATE.primitiveReceiverToken,
458       items.length,
459     );
460     const prepared = prepareDirectChildStyle(child, receiverToken, container);
461     const normalized = preparedStyleValue(prepared) as Readonly<
462       BoxStyle & FlexItemStyle & LayoutItemStyle & Record<string, unknown>
463     >;
464     assertSupportedChildPosition('Flex', child, normalized);
465     rejectUnsupportedItemFields(child, normalized, container);
466     const grow = nonnegativeFactor(normalized.flexGrow ?? 0, 'flexGrow', child, container);
467     const shrink = nonnegativeFactor(
468       normalized.flexShrink ?? 1,
469       'flexShrink',
470       child,
471       container,
472     );
473     const basisValue = normalized.flexBasis ?? 'auto';
474     const minimumProperty = row ? 'minWidth' : 'minHeight';
475     if ((shrink > 0 || basisValue === 'auto') && normalized[minimumProperty] === undefined) {
476       throw childDiagnostic(
477         child,
478         minimumProperty,
479         normalized[minimumProperty],
480         container,
481         'an explicit main-axis minimum is required for shrink or auto basis',
482       );
483     }
484 
485     const mainProperty = row ? 'width' : 'height';
486     const crossProperty = row ? 'height' : 'width';
487     const mainReference = mainSize;
488     const crossReference = crossSize;
489     let measured: { width: number; height: number } | undefined;
490     const specifiedMain = normalized[mainProperty];
491     const specifiedCross = normalized[crossProperty];
492     const needsMeasuredMain = basisValue === 'auto' &&
493       (specifiedMain === undefined || specifiedMain === 'auto');
494     const crossAuto = specifiedCross === undefined || specifiedCross === 'auto';
495     const alignment = normalizeItemAlignment(normalized.alignSelf, child, container);
496     const needsMeasuredCross = crossAuto && alignment !== 'stretch' &&
497       options.alignItems !== 'stretch';
498     if (needsMeasuredMain || needsMeasuredCross || crossAuto) {
499       const constraints = {
500         minWidth: 0,
501         maxWidth: container.width,
502         minHeight: 0,
503         maxHeight: container.height,
504       };
505       const measurementChild = clonePibblElement(child);
506       setPreNormalizedStyle(
507         measurementChild,
508         normalized,
509         child,
510         receiverToken,
511         preparedStyleQuery(prepared),
512       );
513       const result = measurement.measureElement(measurementChild, constraints);
514       if (result.status === 'measured') {
515         measured = result.size;
516       } else if (needsMeasuredMain || (crossAuto && effectiveAlignment(
517         alignment,
518         options.alignItems,
519       ) !== 'stretch')) {
520         throw childDiagnostic(
521           child,
522           needsMeasuredMain ? mainProperty : crossProperty,
523           'auto',
524           container,
525           `measurement is required but unsupported: ${result.reason}`,
526         );
527       }
528     }
529 
530     const baseMain = resolveBasis(
531       basisValue,
532       specifiedMain,
533       measured?.[mainProperty],
534       mainReference,
535       mainProperty,
536       child,
537       container,
538     );
539     const preferredCross = crossAuto ?
540       measured?.[crossProperty] ?? 0 :
541       resolveItemLength(
542         specifiedCross,
543         crossReference,
544         crossProperty,
545         child,
546         container,
547       );
548     const padding = normalizeEdges(normalized.padding, 'padding', childContext(child, container));
549     const paddingMain = row ? padding.left + padding.right : padding.top + padding.bottom;
550     const paddingCross = row ? padding.top + padding.bottom : padding.left + padding.right;
551     const minMain = resolveOptionalBound(
552       normalized[minimumProperty],
553       mainReference,
554       minimumProperty,
555       0,
556       child,
557       container,
558     );
559     const maximumProperty = row ? 'maxWidth' : 'maxHeight';
560     const maxMain = resolveOptionalBound(
561       normalized[maximumProperty],
562       mainReference,
563       maximumProperty,
564       Number.POSITIVE_INFINITY,
565       child,
566       container,
567     );
568     const minCrossProperty = row ? 'minHeight' : 'minWidth';
569     const maxCrossProperty = row ? 'maxHeight' : 'maxWidth';
570     const minCross = resolveOptionalBound(
571       normalized[minCrossProperty],
572       crossReference,
573       minCrossProperty,
574       0,
575       child,
576       container,
577     );
578     const maxCross = resolveOptionalBound(
579       normalized[maxCrossProperty],
580       crossReference,
581       maxCrossProperty,
582       Number.POSITIVE_INFINITY,
583       child,
584       container,
585     );
586     if (minMain > maxMain) {
587       throw childDiagnostic(
588         child,
589         minimumProperty,
590         minMain,
591         container,
592         'minimum must not exceed maximum',
593       );
594     }
595     if (minCross > maxCross) {
596       throw childDiagnostic(
597         child,
598         minCrossProperty,
599         minCross,
600         container,
601         'minimum must not exceed maximum',
602       );
603     }
604     items.push({
605       child,
606       normalized,
607       baseMain,
608       targetMain: baseMain,
609       paddingMain,
610       preferredCross: clamp(preferredCross, minCross, maxCross) + paddingCross,
611       paddingCross,
612       minMain,
613       maxMain,
614       minCross,
615       maxCross,
616       grow,
617       shrink,
618       crossAuto,
619       alignSelf: alignment,
620       receiverToken,
621       query: preparedStyleQuery(prepared),
622     });
623   }
624 
625   const lines = collectLines(items, mainSize, mainGap, options.flexWrap);
626   for (const line of lines) resolveFlexibleLengths(line, mainSize, mainGap);
627   resolveLineCrossSizes(
628     lines,
629     crossSize,
630     crossGap,
631     options.alignContent,
632     options.flexWrap === 'wrap',
633   );
634 
635   const placements: FlexPlacement[] = [];
636   for (const line of lines) {
637     const occupied = line.items.reduce(
638       (total, item) => total + item.targetMain + item.paddingMain,
639       Math.max(0, line.items.length - 1) * mainGap,
640     );
641     const distribution = distributeAlignment(
642       options.justifyContent,
643       mainSize - occupied,
644       line.items.length,
645     );
646     let mainCursor = distribution.start;
647     for (const item of line.items) {
648       const alignment = effectiveAlignment(item.alignSelf, options.alignItems);
649       let outerCross = item.preferredCross;
650       if (alignment === 'stretch' && item.crossAuto) {
651         outerCross = clamp(
652           Math.max(0, line.crossSize - item.paddingCross),
653           item.minCross,
654           item.maxCross,
655         ) + item.paddingCross;
656       }
657       const crossOffset = alignmentOffset(
658         alignment,
659         line.crossSize,
660         outerCross,
661       );
662       const outerMain = item.targetMain + item.paddingMain;
663       const box = row ? {
664         x: container.x + mainCursor,
665         y: container.y + line.crossOffset + crossOffset,
666         width: outerMain,
667         height: outerCross,
668       } : {
669         x: container.x + line.crossOffset + crossOffset,
670         y: container.y + mainCursor,
671         width: outerCross,
672         height: outerMain,
673       };
674       const usedStyle = {
675         ...item.normalized,
676         width: row ? item.targetMain : Math.max(0, outerCross - item.paddingCross),
677         height: row ? Math.max(0, outerCross - item.paddingCross) : item.targetMain,
678       };
679       placements.push({
680         box,
681         element: childWithUsedSize(
682           item.child,
683           usedStyle,
684           usedStyle.width,
685           usedStyle.height,
686           item.receiverToken,
687           item.query,
688         ),
689       });
690       mainCursor += outerMain + mainGap + distribution.between;
691     }
692   }
693   return placements;
694 }
695 
696 function collectLines(
697   items: readonly FlexItem[],
698   mainSize: number,
699   gap: number,
700   wrap: FlexWrap,
701 ): FlexLine[] {
702   const lines: FlexLine[] = [];
703   let current: FlexItem[] = [];
704   let occupied = 0;
705   for (const item of items) {
706     const hypothetical = clamp(item.baseMain, item.minMain, item.maxMain) +
707       item.paddingMain;
708     const next = current.length === 0 ? hypothetical : occupied + gap + hypothetical;
709     if (wrap === 'wrap' && current.length > 0 && next > mainSize) {
710       lines.push({ items: current, crossSize: 0, crossOffset: 0 });
711       current = [];
712       occupied = 0;
713     }
714     occupied = current.length === 0 ? hypothetical : occupied + gap + hypothetical;
715     current.push(item);
716   }
717   if (current.length > 0) {
718     lines.push({ items: current, crossSize: 0, crossOffset: 0 });
719   }
720   return lines;
721 }
722 
723 function resolveFlexibleLengths(
724   line: FlexLine,
725   mainSize: number,
726   gap: number,
727 ): void {
728   const gapSpace = Math.max(0, line.items.length - 1) * gap;
729   const baseOuter = line.items.reduce(
730     (total, item) => total + item.baseMain + item.paddingMain,
731     0,
732   );
733   const hypotheticalOuter = line.items.reduce(
734     (total, item) => total +
735       clamp(item.baseMain, item.minMain, item.maxMain) + item.paddingMain,
736     0,
737   );
738   const growing = hypotheticalOuter + gapSpace < mainSize;
739   const initialFree = mainSize - gapSpace - baseOuter;
740   const frozen = new Set<FlexItem>();
741   for (const item of line.items) {
742     item.targetMain = item.baseMain;
743     const hypothetical = clamp(item.baseMain, item.minMain, item.maxMain);
744     if (
745       (growing ? item.grow : item.shrink) === 0 ||
746       (growing && item.baseMain > hypothetical) ||
747       (!growing && item.baseMain < hypothetical)
748     ) {
749       item.targetMain = hypothetical;
750       frozen.add(item);
751     }
752   }
753 
754   while (frozen.size < line.items.length) {
755     const fixed = line.items.reduce(
756       (total, item) => total +
757         (frozen.has(item) ? item.targetMain : item.baseMain) +
758         item.paddingMain,
759       gapSpace,
760     );
761     let free = mainSize - fixed;
762     const unfrozen = line.items.filter(item => !frozen.has(item));
763     const rawFactor = growing ?
764       unfrozen.reduce((total, item) => total + item.grow, 0) :
765       unfrozen.reduce((total, item) => total + item.shrink, 0);
766     const scaledFactor = growing ? rawFactor :
767       unfrozen.reduce((total, item) => total + item.shrink * item.baseMain, 0);
768     if (scaledFactor === 0) {
769       for (const item of unfrozen) {
770         item.targetMain = clamp(item.baseMain, item.minMain, item.maxMain);
771         frozen.add(item);
772       }
773       break;
774     }
775     if (rawFactor < 1) {
776       const partialFree = initialFree * rawFactor;
777       if (Math.abs(partialFree) < Math.abs(free)) free = partialFree;
778     }
779     const violations: { item: FlexItem; amount: number }[] = [];
780     for (const item of unfrozen) {
781       const share = growing ? item.grow / scaledFactor :
782         item.shrink * item.baseMain / scaledFactor;
783       const candidate = item.baseMain + free * share;
784       const clamped = clamp(candidate, item.minMain, item.maxMain);
785       item.targetMain = clamped;
786       if (clamped !== candidate) {
787         violations.push({ item, amount: clamped - candidate });
788       }
789     }
790     if (violations.length === 0) break;
791     const totalViolation = violations.reduce(
792       (total, violation) => total + violation.amount,
793       0,
794     );
795     for (const violation of violations) {
796       if (
797         totalViolation === 0 ||
798         (totalViolation > 0 && violation.amount > 0) ||
799         (totalViolation < 0 && violation.amount < 0)
800       ) {
801         frozen.add(violation.item);
802       }
803     }
804   }
805 }
806 
807 function resolveLineCrossSizes(
808   lines: FlexLine[],
809   crossSize: number,
810   gap: number,
811   alignment: ResolvedFlexStyle['alignContent'],
812   multiLine: boolean,
813 ): void {
814   if (lines.length === 0) return;
815   for (const line of lines) {
816     line.crossSize = Math.max(0, ...line.items.map(item => item.preferredCross));
817   }
818   if (lines.length === 1 && !multiLine) {
819     lines[0].crossSize = crossSize;
820     lines[0].crossOffset = 0;
821     return;
822   }
823   const occupied = lines.reduce(
824     (total, line) => total + line.crossSize,
825     Math.max(0, lines.length - 1) * gap,
826   );
827   const free = crossSize - occupied;
828   if (alignment === 'stretch' && free > 0) {
829     const addition = free / lines.length;
830     for (const line of lines) line.crossSize += addition;
831   }
832   const distribution = alignment === 'stretch' ?
833     { start: 0, between: 0 } :
834     distributeAlignment(alignment, free, lines.length);
835   let cursor = distribution.start;
836   for (const line of lines) {
837     line.crossOffset = cursor;
838     cursor += line.crossSize + gap + distribution.between;
839   }
840 }
841 
842 function distributeAlignment(
843   alignment: MainAlignment | CrossAlignment,
844   free: number,
845   count: number,
846 ): { start: number; between: number } {
847   if (count === 0 || alignment === 'flex-start' || alignment === 'stretch') {
848     return { start: 0, between: 0 };
849   }
850   if (free < 0) {
851     if (alignment === 'flex-end') return { start: free, between: 0 };
852     if (alignment === 'center' || alignment === 'space-around' ||
853       alignment === 'space-evenly') {
854       return { start: free / 2, between: 0 };
855     }
856     return { start: 0, between: 0 };
857   }
858   if (alignment === 'flex-end') return { start: free, between: 0 };
859   if (alignment === 'center') return { start: free / 2, between: 0 };
860   if (alignment === 'space-between') {
861     return count === 1 ? { start: 0, between: 0 } :
862       { start: 0, between: free / (count - 1) };
863   }
864   if (alignment === 'space-around') {
865     const between = free / count;
866     return { start: between / 2, between };
867   }
868   if (alignment === 'space-evenly') {
869     const between = free / (count + 1);
870     return { start: between, between };
871   }
872   return { start: 0, between: 0 };
873 }
874 
875 function normalizeFlexOptions(
876   style: Readonly<FlexStyle>,
877   container: Readonly<LayoutBox>,
878 ) {
879   const flexDirection = supported(style.flexDirection ?? 'row', ['row', 'column'], 'flexDirection', container);
880   const flexWrap = supported(style.flexWrap ?? 'nowrap', ['nowrap', 'wrap'], 'flexWrap', container);
881   const justifyContent = supported(
882     style.justifyContent ?? 'flex-start',
883     ['flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly'],
884     'justifyContent',
885     container,
886   );
887   const alignItems = supported(
888     style.alignItems ?? 'stretch',
889     ['stretch', 'flex-start', 'flex-end', 'center'],
890     'alignItems',
891     container,
892   );
893   const alignContent = supported(
894     style.alignContent ?? 'stretch',
895     ['stretch', 'flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly'],
896     'alignContent',
897     container,
898   );
899   const gap = nonnegativeGap(style.gap ?? 0, 'gap', container);
900   return {
901     flexDirection: flexDirection as FlexDirection,
902     flexWrap: flexWrap as FlexWrap,
903     justifyContent: justifyContent as MainAlignment,
904     alignItems: alignItems as CrossAlignment,
905     alignContent: alignContent as CrossAlignment | MainAlignment,
906     rowGap: nonnegativeGap(style.rowGap ?? gap, 'rowGap', container),
907     columnGap: nonnegativeGap(style.columnGap ?? gap, 'columnGap', container),
908   };
909 }
910 
911 function supported(
912   value: string,
913   accepted: readonly string[],
914   property: string,
915   container: Readonly<LayoutBox>,
916 ): string {
917   if (!accepted.includes(value)) throw optionDiagnostic(property, value, container);
918   return value;
919 }
920 
921 function nonnegativeGap(
922   value: unknown,
923   property: string,
924   container: Readonly<LayoutBox>,
925 ): number {
926   if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
927     throw optionDiagnostic(property, value, container);
928   }
929   return value;
930 }
931 
932 function nonnegativeFactor(
933   value: number,
934   property: string,
935   child: PibblElement<any>,
936   container: Readonly<LayoutBox>,
937 ): number {
938   if (!Number.isFinite(value) || value < 0) {
939     throw childDiagnostic(
940       child,
941       property,
942       value,
943       container,
944       'must be finite and nonnegative',
945     );
946   }
947   return value;
948 }
949 
950 function resolveBasis(
951   basis: FlexItemStyle['flexBasis'],
952   specifiedMain: BoxStyle['width'],
953   measuredMain: number | undefined,
954   reference: number,
955   property: 'width' | 'height',
956   child: PibblElement<any>,
957   container: Readonly<LayoutBox>,
958 ): number {
959   const value = basis === 'auto' || basis === undefined ? specifiedMain : basis;
960   if (value === undefined || value === 'auto') {
961     if (measuredMain === undefined) {
962       throw childDiagnostic(
963         child,
964         property,
965         value ?? 'auto',
966         container,
967         'auto flex basis requires supported pure measurement',
968       );
969     }
970     return measuredMain;
971   }
972   return resolveItemLength(value, reference, 'flexBasis', child, container);
973 }
974 
975 function resolveItemLength(
976   value: Exclude<BoxStyle['width'], undefined>,
977   reference: number,
978   property: string,
979   child: PibblElement<any>,
980   container: Readonly<LayoutBox>,
981 ): number {
982   const resolved = resolveLength(value, reference, property, childContext(child, container));
983   if (resolved === undefined || resolved < 0) {
984     throw childDiagnostic(
985       child,
986       property,
987       value,
988       container,
989       'must resolve to a finite nonnegative length',
990     );
991   }
992   return resolved;
993 }
994 
995 function resolveOptionalBound(
996   value: BoxStyle['minWidth'],
997   reference: number,
998   property: string,
999   fallback: number,
1000   child: PibblElement<any>,
1001   container: Readonly<LayoutBox>,
1002 ): number {
1003   if (value === undefined) return fallback;
1004   return resolveItemLength(value, reference, property, child, container);
1005 }
1006 
1007 function normalizeItemAlignment(
1008   value: LayoutItemStyle['alignSelf'],
1009   child: PibblElement<any>,
1010   container: Readonly<LayoutBox>,
1011 ): CrossAlignment | 'auto' {
1012   if (value === undefined || value === 'auto') return 'auto';
1013   if (value === 'stretch' || value === 'flex-start' ||
1014     value === 'flex-end' || value === 'center') return value;
1015   throw childDiagnostic(
1016     child,
1017     'alignSelf',
1018     value,
1019     container,
1020     'uses an unsupported flex item alignment',
1021   );
1022 }
1023 
1024 function effectiveAlignment(
1025   value: CrossAlignment | 'auto',
1026   fallback: CrossAlignment,
1027 ): CrossAlignment {
1028   return value === 'auto' ? fallback : value;
1029 }
1030 
1031 function alignmentOffset(
1032   alignment: CrossAlignment,
1033   lineSize: number,
1034   itemSize: number,
1035 ): number {
1036   if (alignment === 'center') return (lineSize - itemSize) / 2;
1037   if (alignment === 'flex-end') return lineSize - itemSize;
1038   return 0;
1039 }
1040 
1041 function rejectUnsupportedItemFields(
1042   child: PibblElement<any>,
1043   style: Readonly<Record<string, unknown>>,
1044   container: Readonly<LayoutBox>,
1045 ): void {
1046   for (const property of ['order', 'margin', 'marginLeft', 'marginRight', 'marginTop', 'marginBottom']) {
1047     if (style[property] !== undefined) {
1048       throw childDiagnostic(
1049         child,
1050         property,
1051         style[property],
1052         container,
1053         'uses an unsupported flex item feature',
1054       );
1055     }
1056   }
1057 }
1058 
1059 function clamp(value: number, minimum: number, maximum: number): number {
1060   return Math.min(maximum, Math.max(minimum, value));
1061 }
1062 
1063 function assertFiniteBox(container: Readonly<LayoutBox>): void {
1064   for (const [property, value] of Object.entries(container)) {
1065     if (!Number.isFinite(value) ||
1066       ((property === 'width' || property === 'height') && value < 0)) {
1067       throw optionDiagnostic(property, value, container);
1068     }
1069   }
1070 }
1071 
1072 function optionDiagnostic(
1073   property: string,
1074   value: unknown,
1075   container: Readonly<LayoutBox>,
1076 ) {
1077   return layoutDiagnostic({
1078     component: 'Flex',
1079     property,
1080     value,
1081     algorithm: 'flex',
1082     constraints: constraintsFor(container),
1083     reason: 'uses an unsupported flex value',
1084   });
1085 }
1086 
1087 function childDiagnostic(
1088   child: PibblElement<any>,
1089   property: string,
1090   value: unknown,
1091   container: Readonly<LayoutBox>,
1092   reason: string,
1093 ) {
1094   return layoutDiagnostic({
1095     component: child.type.name || 'Anonymous',
1096     property,
1097     value,
1098     algorithm: 'flex',
1099     constraints: constraintsFor(container),
1100     reason,
1101   });
1102 }
1103 
1104 function childContext(
1105   child: PibblElement<any>,
1106   container: Readonly<LayoutBox>,
1107 ) {
1108   return {
1109     component: child.type.name || 'Anonymous',
1110     algorithm: 'flex',
1111     constraints: constraintsFor(container),
1112   };
1113 }
1114 
1115 function constraintsFor(container: Readonly<LayoutBox>): Constraints {
1116   return {
1117     minWidth: 0,
1118     maxWidth: container.width,
1119     minHeight: 0,
1120     maxHeight: container.height,
1121   };
1122 }
1123
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.