# packages/core/src/lib/layout/flow.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/flow.ts#L165). [Back to reference](/reference/components/flow/)
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 { setPreNormalizedStyle } from '../style/resolve-dispatch.js';
14 import type { BoxStyle, LayoutItemStyle, ResolvedBoxStyle } from '../style/types.js';
15 import type {
16   CanvasMeasurementService,
17   PibblNodeInput,
18   MeasureInput,
19   MeasureResult,
20   RenderingContext2D,
21   SystemStyle,
22 } from '../types.js';
23 import {
24   childWithUsedSize,
25   materializeLayoutChildren,
26   prepareDirectChildStyle,
27   placeDirectChildren,
28   prepareLayoutChildren,
29   resolveContainerBox,
30   resolveDirectChildBox,
31 } from './absolute.js';
32 import { pushLayoutBox } from './context.js';
33 import { recordLayoutEvaluation } from './diagnostics.js';
34 import { assertSupportedChildPosition } from './positioning-diagnostics.js';
35 import { measureElement } from './measure.js';
36 import type { Constraints, LayoutBox } from './types.js';
37 
38 type FlowDirection = 'horizontal' | 'vertical';
39 type FlowAlignment = 'start' | 'center' | 'end' | 'stretch';
40 
41 /**
42  * Supported geometry and presentation properties for Flow.
43  *
44  * @see {@link BoxStyle}
45  * @see {@link LayoutItemStyle}
46  * @see {@link Flow}
47  */
48 export interface FlowStyle extends BoxStyle, LayoutItemStyle {
49   /** Direction in which this operation proceeds. See {@link FlowDirection}. */
50   direction?: FlowDirection;
51   /** Whether content may wrap into additional lines. See {@link FlowStyle}. */
52   wrap?: boolean;
53   /** Spacing between adjacent items. See {@link FlowStyle}. */
54   gap?: number;
55   /** Space between wrapped flow lines. See {@link FlowStyle}. */
56   lineGap?: number;
57   /** Default alignment of children on the cross or block axis. See {@link FlowAlignment}. */
58   alignItems?: FlowAlignment;
59 }
60 
61 /**
62  * Authored inputs for Flow, including the declared data and presentation options.
63  *
64  * @see {@link PibblNodeInput}
65  * @see {@link Flow}
66  */
67 export interface FlowProps extends PibblStructuralEventProps {
68   /** Descendant content or the callback that supplies it. See {@link PibblNodeInput}. */
69   children: PibblNodeInput;
70 }
71 
72 interface ResolvedFlowStyle extends SystemStyle {
73   box: ResolvedBoxStyle;
74   overflow: 'visible' | 'clip';
75   direction: FlowDirection;
76   wrap: boolean;
77   gap: number;
78   lineGap: number;
79   alignItems: FlowAlignment;
80 }
81 
82 interface FlowItem {
83   child: PibblElement<any>;
84   normalized: Readonly<SystemStyle>;
85   width: number;
86   height: number;
87   horizontalPadding: number;
88   verticalPadding: number;
89   alignment: FlowAlignment;
90   receiverToken: object;
91   query?: PreparedQuery;
92 }
93 
94 export interface FlowMeasurementInput {
95   service: CanvasMeasurementService;
96   measureElement(
97     element: PibblElement<any>,
98     constraints: Readonly<Constraints>,
99   ): MeasureResult;
100 }
101 
102 interface FlowPlacement {
103   box: LayoutBox;
104   element: PibblElement<any>;
105 }
106 
107 function renderFlow(
108   props: FlowProps,
109   style: Readonly<ResolvedFlowStyle>,
110   ctx: RenderingContext2D,
111 ) {
112   wireStructuralEvents(props);
113   const children = prepareLayoutChildren(props.children, 'Flow');
114   recordLayoutEvaluation();
115   const content = style.box.contentBox;
116   ctx.translate(content.x, content.y);
117   const localContent = Object.freeze({
118     x: 0,
119     y: 0,
120     width: content.width,
121     height: content.height,
122   });
123   const releaseLayout = pushLayoutBox(localContent);
124   GLOBAL_STATE.componentRefs!.onAfterRender = releaseLayout;
125   const service = {
126     measureText(value: string, font: string) {
127       ctx.save();
128       try {
129         ctx.font = font;
130         return ctx.measureText(value);
131       } finally {
132         ctx.restore();
133       }
134     },
135   };
136   const placements = resolveFlowPlacements(
137     localContent,
138     children,
139     style,
140     {
141       service,
142       measureElement: (element, constraints) =>
143         measureElement(element, constraints, service),
144     },
145   );
146   let index = 0;
147   return placeDirectChildren(
148     children,
149     localContent,
150     () => placements[index++],
151     style.overflow,
152   );
153 }
154 
155 /**
156  * Describes sequential flow layout for JSX or createElement authoring.
157  *
158  * @param props - Authored component inputs, supplied through JSX or createElement. See the linked
159  * props and style types.
160  * @throws When called directly; Pibbl mounts this component through JSX or createElement.
161  *
162  * @see {@link FlowProps}
163  * @see {@link FlowStyle}
164  */
165 export const Flow = definePrimitive<
166   FlowProps,
167   FlowStyle,
168   FlowStyle,
169   ResolvedFlowStyle
170 >(renderFlow, {
171   childInput: 'structural',
172   resolveStyle: (style, context) => ({
173     box: resolveContainerBox(style, context, 'Flow', 'flow'),
174     overflow: style.overflow ?? 'visible',
175     ...normalizeFlowOptions(style, context.allocation),
176   }),
177   measure: input => measureFlow(input),
178 });
179 
180 export function layoutFlow(
181   container: Readonly<LayoutBox>,
182   children: PibblNodeInput,
183   style: Readonly<FlowStyle>,
184   measurement: FlowMeasurementInput,
185 ): LayoutBox[] {
186   const prepared = materializeLayoutChildren(children, 'Flow');
187   return resolveFlowPlacements(container, prepared, style, measurement)
188     .map(placement => placement.box);
189 }
190 
191 function resolveFlowPlacements(
192   container: Readonly<LayoutBox>,
193   children: readonly PibblElement<any>[],
194   style: Readonly<FlowStyle>,
195   measurement: FlowMeasurementInput,
196 ): FlowPlacement[] {
197   assertFiniteContainer(container);
198   const options = normalizeFlowOptions(style, container);
199   const items: FlowItem[] = [];
200   for (const child of children) {
201     const receiverToken = getChildPrimitiveReceiverToken(
202       GLOBAL_STATE.renderTransaction,
203       GLOBAL_STATE.primitiveReceiverToken,
204       items.length,
205     );
206     const prepared = prepareDirectChildStyle(child, receiverToken, container);
207     const normalized = preparedStyleValue(prepared) as Readonly<
208       BoxStyle & LayoutItemStyle
209     >;
210     assertSupportedChildPosition('Flow', child, normalized);
211     const needsWidth = normalized.width === undefined || normalized.width === 'auto';
212     const needsHeight = normalized.height === undefined || normalized.height === 'auto';
213     let measuredWidth: number | undefined;
214     let measuredHeight: number | undefined;
215     if (needsWidth || needsHeight) {
216       const constraints = {
217         minWidth: 0,
218         maxWidth: container.width,
219         minHeight: 0,
220         maxHeight: container.height,
221       };
222       const measurementChild = clonePibblElement(child);
223       setPreNormalizedStyle(
224         measurementChild,
225         normalized,
226         child,
227         receiverToken,
228         preparedStyleQuery(prepared),
229       );
230       const result = measurement.measureElement(measurementChild, constraints);
231       if (result.status === 'unsupported') {
232         const axis = needsWidth ? 'width' : 'height';
233         throw layoutDiagnostic({
234           component: child.type.name || 'Anonymous',
235           property: axis,
236           value: normalized[axis] ?? 'auto',
237           algorithm: 'flow',
238           constraints,
239           reason: `measurement is required but unsupported: ${result.reason}`,
240         });
241       }
242       measuredWidth = result.size.width;
243       measuredHeight = result.size.height;
244     }
245     const resolvedStyle = {
246       ...normalized,
247       width: needsWidth ? measuredWidth : normalized.width,
248       height: needsHeight ? measuredHeight : normalized.height,
249     };
250     const resolved = resolveDirectChildBox(
251       container,
252       child,
253       'flow',
254       resolvedStyle,
255     );
256     const box = resolved.borderBox;
257     items.push({
258       child,
259       normalized: Object.freeze(resolvedStyle),
260       width: box.width,
261       height: box.height,
262       horizontalPadding: box.width - resolved.contentBox.width,
263       verticalPadding: box.height - resolved.contentBox.height,
264       alignment: resolveItemAlignment(
265         normalized.alignSelf,
266         options.alignItems,
267         child,
268         container,
269       ),
270       receiverToken,
271       query: preparedStyleQuery(prepared),
272     });
273   }
274 
275   const boxes = arrangeFlowItems(container, items, options);
276   return boxes.map((box, index) => ({
277     box,
278     element: childWithUsedSize(
279       items[index].child,
280       items[index].normalized,
281       Math.max(0, box.width - items[index].horizontalPadding),
282       Math.max(0, box.height - items[index].verticalPadding),
283       items[index].receiverToken,
284       items[index].query,
285     ),
286   }));
287 }
288 
289 function measureFlow(
290   input: MeasureInput<FlowProps, FlowStyle>,
291 ): MeasureResult {
292   const children = prepareLayoutChildren(input.props.children, 'Flow');
293   const widthDefinite = input.style.width !== undefined &&
294     input.style.width !== 'auto';
295   const heightDefinite = input.style.height !== undefined &&
296     input.style.height !== 'auto';
297   const provisional = provisionalFlowBox(input.style, input.constraints);
298   if (widthDefinite && heightDefinite) {
299     return { status: 'measured', size: {
300       width: provisional.content.width,
301       height: provisional.content.height,
302     } };
303   }
304 
305   const placements = resolveFlowPlacements(
306     provisional.content,
307     children,
308     input.style,
309     input,
310   );
311   let intrinsicWidth = 0;
312   let intrinsicHeight = 0;
313   for (const placement of placements) {
314     intrinsicWidth = Math.max(
315       intrinsicWidth,
316       placement.box.x - provisional.content.x + placement.box.width,
317     );
318     intrinsicHeight = Math.max(
319       intrinsicHeight,
320       placement.box.y - provisional.content.y + placement.box.height,
321     );
322   }
323   validateMeasuredExtent(intrinsicWidth, 'width', input.constraints);
324   validateMeasuredExtent(intrinsicHeight, 'height', input.constraints);
325   return { status: 'measured', size: {
326     width: widthDefinite ? provisional.content.width : intrinsicWidth,
327     height: heightDefinite ? provisional.content.height : intrinsicHeight,
328   } };
329 }
330 
331 function provisionalFlowBox(
332   style: Readonly<FlowStyle>,
333   constraints: Readonly<Constraints>,
334 ): { border: LayoutBox; content: LayoutBox } {
335   const diagnosticContext = {
336     component: 'Flow',
337     algorithm: 'measurement',
338     constraints,
339   };
340   const padding = normalizeEdges(style.padding, 'padding', diagnosticContext);
341   const width = finiteMeasurementBound(
342     constraints.maxWidth,
343     [style.width, style.minWidth, style.maxWidth],
344     padding.left + padding.right,
345     'width',
346     constraints,
347   );
348   const height = finiteMeasurementBound(
349     constraints.maxHeight,
350     [style.height, style.minHeight, style.maxHeight],
351     padding.top + padding.bottom,
352     'height',
353     constraints,
354   );
355   const box = resolveContainerBox(style, {
356     allocation: { x: 0, y: 0, width, height },
357     percentageBasis: { x: 0, y: 0, width, height },
358     constraints,
359     component: 'Flow',
360     algorithm: 'render-dispatch',
361   }, 'Flow', 'measurement');
362   return { border: box.borderBox, content: box.contentBox };
363 }
364 
365 function finiteMeasurementBound(
366   maximum: number,
367   specified: readonly (BoxStyle['width'] | undefined)[],
368   padding: number,
369   property: 'width' | 'height',
370   constraints: Readonly<Constraints>,
371 ): number {
372   if (Number.isFinite(maximum)) return maximum;
373   const numeric = specified.filter(
374     (value): value is number => typeof value === 'number' && Number.isFinite(value),
375   );
376   if (numeric.length > 0) {
377     const bound = Math.max(...numeric) + padding;
378     if (Number.isFinite(bound)) return bound;
379     throw layoutDiagnostic({
380       component: 'Flow',
381       property,
382       value: bound,
383       algorithm: 'measurement',
384       constraints,
385       reason: 'measurement allocation arithmetic must remain finite',
386     });
387   }
388   const percentage = specified.find(
389     value => typeof value === 'string' && value.endsWith('%'),
390   );
391   if (percentage !== undefined) {
392     throw layoutDiagnostic({
393       component: 'Flow',
394       property,
395       value: percentage,
396       algorithm: 'measurement',
397       constraints,
398       reason: 'requires a definite finite percentage reference',
399     });
400   }
401   return Number.MAX_SAFE_INTEGER;
402 }
403 
404 function validateMeasuredExtent(
405   value: number,
406   property: string,
407   constraints: Readonly<Constraints>,
408 ): void {
409   if (!Number.isFinite(value) || value < 0) {
410     throw layoutDiagnostic({
411       component: 'Flow',
412       property,
413       value,
414       algorithm: 'measurement',
415       constraints,
416       reason: 'intrinsic flow extent must be finite and nonnegative',
417     });
418   }
419 }
420 
421 function arrangeFlowItems(
422   container: Readonly<LayoutBox>,
423   items: readonly FlowItem[],
424   options: ReturnType<typeof normalizeFlowOptions>,
425 ): LayoutBox[] {
426   const horizontal = options.direction === 'horizontal';
427   const mainBound = horizontal ? container.width : container.height;
428   const lines: FlowItem[][] = [];
429   let line: FlowItem[] = [];
430   let occupiedMain = 0;
431   for (const item of items) {
432     const mainSize = horizontal ? item.width : item.height;
433     const nextMain = line.length === 0 ?
434       mainSize :
435       occupiedMain + options.gap + mainSize;
436     if (options.wrap && line.length > 0 && nextMain > mainBound) {
437       lines.push(line);
438       line = [];
439       occupiedMain = 0;
440     }
441     occupiedMain = line.length === 0 ?
442       mainSize :
443       occupiedMain + options.gap + mainSize;
444     line.push(item);
445   }
446   if (line.length > 0) lines.push(line);
447 
448   const placements: LayoutBox[] = [];
449   let crossCursor = 0;
450   for (const currentLine of lines) {
451     const lineCross = Math.max(0, ...currentLine.map(item =>
452       horizontal ? item.height : item.width,
453     ));
454     let mainCursor = 0;
455     for (const item of currentLine) {
456       const itemMain = horizontal ? item.width : item.height;
457       const itemCross = horizontal ? item.height : item.width;
458       const crossOffset = alignCross(lineCross, itemCross, item.alignment);
459       const placedCross = item.alignment === 'stretch' ?
460         Math.max(0, lineCross) :
461         itemCross;
462       placements.push(horizontal ? {
463         x: container.x + mainCursor,
464         y: container.y + crossCursor + crossOffset,
465         width: itemMain,
466         height: placedCross,
467       } : {
468         x: container.x + crossCursor + crossOffset,
469         y: container.y + mainCursor,
470         width: placedCross,
471         height: itemMain,
472       });
473       mainCursor += itemMain + options.gap;
474     }
475     crossCursor += lineCross + options.lineGap;
476   }
477   return placements;
478 }
479 
480 function normalizeFlowOptions(
481   style: Readonly<FlowStyle>,
482   container: Readonly<LayoutBox>,
483 ) {
484   const direction = style.direction ?? 'horizontal';
485   if (direction !== 'horizontal' && direction !== 'vertical') {
486     throw optionDiagnostic('direction', direction, container);
487   }
488   if (style.wrap !== undefined && typeof style.wrap !== 'boolean') {
489     throw optionDiagnostic('wrap', style.wrap, container);
490   }
491   const alignItems = style.alignItems ?? 'start';
492   if (
493     alignItems !== 'start' && alignItems !== 'center' &&
494     alignItems !== 'end' && alignItems !== 'stretch'
495   ) {
496     throw optionDiagnostic('alignItems', alignItems, container);
497   }
498   return {
499     direction,
500     wrap: style.wrap ?? false,
501     gap: nonnegativeOption(style.gap ?? 0, 'gap', container),
502     lineGap: nonnegativeOption(style.lineGap ?? 0, 'lineGap', container),
503     alignItems,
504   };
505 }
506 
507 function nonnegativeOption(
508   value: number,
509   property: string,
510   container: Readonly<LayoutBox>,
511 ): number {
512   if (!Number.isFinite(value) || value < 0) {
513     throw optionDiagnostic(property, value, container);
514   }
515   return value;
516 }
517 
518 function resolveItemAlignment(
519   value: LayoutItemStyle['alignSelf'],
520   fallback: FlowAlignment,
521   child: PibblElement<any>,
522   container: Readonly<LayoutBox>,
523 ): FlowAlignment {
524   if (value === undefined || value === 'auto') return fallback;
525   if (value === 'start' || value === 'center' || value === 'end' || value === 'stretch') {
526     return value;
527   }
528   throw layoutDiagnostic({
529     component: child.type.name || 'Anonymous',
530     property: 'alignSelf',
531     value,
532     algorithm: 'flow',
533     constraints: constraintsFor(container),
534     reason: 'uses an unsupported flow alignment value',
535   });
536 }
537 
538 function alignCross(
539   lineCross: number,
540   itemCross: number,
541   alignment: FlowAlignment,
542 ): number {
543   if (alignment === 'center') return (lineCross - itemCross) / 2;
544   if (alignment === 'end') return lineCross - itemCross;
545   return 0;
546 }
547 
548 function assertFiniteContainer(container: Readonly<LayoutBox>): void {
549   for (const [property, value] of Object.entries(container)) {
550     if (!Number.isFinite(value) ||
551       ((property === 'width' || property === 'height') && value < 0)) {
552       throw optionDiagnostic(property, value, container);
553     }
554   }
555 }
556 
557 function optionDiagnostic(
558   property: string,
559   value: unknown,
560   container: Readonly<LayoutBox>,
561 ) {
562   return layoutDiagnostic({
563     component: 'Flow',
564     property,
565     value,
566     algorithm: 'flow',
567     constraints: constraintsFor(container),
568     reason: 'uses an unsupported flow value',
569   });
570 }
571 
572 function constraintsFor(container: Readonly<LayoutBox>) {
573   return {
574     minWidth: 0,
575     maxWidth: container.width,
576     minHeight: 0,
577     maxHeight: container.height,
578   };
579 }
580
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.