# packages/core/src/lib/layout/absolute.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/absolute.ts#L126). [Back to reference](/reference/components/absolute/)
1 import { ResponsiveStylePreparation, preparedStyleValue, preparedStyleQuery, type PreparedQuery } from '../style/responsive.js';
2 import { definePrimitive } from '../define-primitive.js';
3 import { EMPTY_STYLE } from '../style/empty-style.js';
4 import { materializeContainerChildren } from '../element/children.js';
5 import { clonePibblElement } from '../element/create-element.js';
6 import {
7   getPrimitiveDefinition,
8   getChildPrimitiveReceiverToken,
9   setPlacementConsumed,
10 } from '../element/metadata.js';
11 import { resolvePrimitiveStyleInput } from '../element/resolve-primitive-inputs.js';
12 import type { PibblElement } from '../element/types.js';
13 import { GLOBAL_STATE } from '../global-state.js';
14 import { normalizeEdges } from '../style/normalize.js';
15 import { resolveLength } from '../style/resolve-length.js';
16 import {
17   extractSystemFilter,
18   setPreNormalizedStyle,
19   withoutSystemFilter,
20 } from '../style/resolve-dispatch.js';
21 import type {
22   BoxStyle,
23   LayoutItemStyle,
24   ResolvedBoxStyle,
25 } from '../style/types.js';
26 import type {
27   PibblNodeInput,
28   PibblRenderTransaction,
29   RenderingContext2D,
30   StyleResolutionContext,
31   SystemStyle,
32 } from '../types.js';
33 import { layoutDiagnostic } from '../style/diagnostics.js';
34 import {
35   type PibblStructuralEventProps,
36   wireStructuralEvents,
37 } from '../components/structural-events.js';
38 import { pushLayoutBox } from './context.js';
39 import { recordLayoutEvaluation } from './diagnostics.js';
40 import { resolveBox } from './box.js';
41 import {
42   createPlacementIdentityHint,
43   placeChild,
44 } from './place-child.js';
45 import type { LayoutBox } from './types.js';
46 import { withReceiverInputProvision } from '../signals/input-provision.js';
47 
48 /**
49  * Supported geometry and presentation properties for Absolute.
50  *
51  * @see {@link BoxStyle}
52  * @see {@link LayoutItemStyle}
53  * @see {@link Absolute}
54  */
55 export type AbsoluteStyle = BoxStyle & LayoutItemStyle;
56 
57 /**
58  * Authored inputs for Absolute, including the declared data and presentation options.
59  *
60  * @see {@link PibblNodeInput}
61  * @see {@link Absolute}
62  */
63 export interface AbsoluteProps extends PibblStructuralEventProps {
64   /** Descendant content or the callback that supplies it. See {@link PibblNodeInput}. */
65   children: PibblNodeInput;
66 }
67 
68 interface ResolvedAbsoluteStyle extends SystemStyle {
69   box: ResolvedBoxStyle;
70   overflow: 'visible' | 'clip';
71 }
72 
73 type LayoutReceiver = 'Absolute' | 'Overlay' | 'Flow' | 'Flex' | 'Grid';
74 
75 const preparedLayoutTransactions = new WeakMap<
76   PibblRenderTransaction,
77   WeakMap<object, readonly PibblElement<any>[]>
78 >();
79 
80 function renderAbsolute(
81   props: AbsoluteProps,
82   style: Readonly<ResolvedAbsoluteStyle>,
83   ctx: RenderingContext2D,
84 ) {
85   wireStructuralEvents(props);
86   const children = prepareLayoutChildren(props.children, 'Absolute');
87   recordLayoutEvaluation();
88   const content = style.box.contentBox;
89   ctx.translate(content.x, content.y);
90   const localContent = Object.freeze({
91     x: 0,
92     y: 0,
93     width: content.width,
94     height: content.height,
95   });
96   const releaseLayout = pushLayoutBox(localContent);
97   GLOBAL_STATE.componentRefs!.onAfterRender = releaseLayout;
98 
99   let occurrence = 0;
100   return placeDirectChildren(
101     children,
102     localContent,
103     child => resolveAbsoluteChildPlacement(
104       localContent,
105       child,
106       getChildPrimitiveReceiverToken(
107         GLOBAL_STATE.renderTransaction,
108         GLOBAL_STATE.primitiveReceiverToken,
109         occurrence++,
110       ),
111     ),
112     style.overflow,
113   );
114 }
115 
116 /**
117  * Describes absolute layout for JSX or createElement authoring.
118  *
119  * @param props - Authored component inputs, supplied through JSX or createElement. See the linked
120  * props and style types.
121  * @throws When called directly; Pibbl mounts this component through JSX or createElement.
122  *
123  * @see {@link AbsoluteProps}
124  * @see {@link AbsoluteStyle}
125  */
126 export const Absolute = definePrimitive<
127   AbsoluteProps,
128   AbsoluteStyle,
129   AbsoluteStyle,
130   ResolvedAbsoluteStyle
131 >(renderAbsolute, {
132   childInput: 'structural',
133   resolveStyle: (style, context) => ({
134     box: resolveContainerBox(style, context, 'Absolute', 'absolute'),
135     overflow: style.overflow ?? 'visible',
136   }),
137 });
138 
139 /** @internal Resolves a layout container without inspecting its children. */
140 export function resolveContainerBox(
141   style: Readonly<BoxStyle>,
142   context: Readonly<StyleResolutionContext>,
143   component: string,
144   algorithm: string,
145 ): ResolvedBoxStyle {
146   return resolveLayoutBox(style, context, component, algorithm, false);
147 }
148 
149 export function placeAbsoluteChild(
150   container: Readonly<LayoutBox>,
151   child: PibblElement<any>,
152 ): LayoutBox {
153   return resolveAbsoluteChildPlacement(container, child).box;
154 }
155 
156 function resolveAbsoluteChildPlacement(
157   container: Readonly<LayoutBox>,
158   child: PibblElement<any>,
159   receiverToken?: object,
160 ): { box: LayoutBox; element: PibblElement<any> } {
161   const prepared = prepareDirectChildStyle(child, receiverToken, container);
162   const style = preparedStyleValue(prepared) as Readonly<
163     BoxStyle & LayoutItemStyle
164   >;
165   const resolved = resolveDirectChildBox(container, child, 'absolute', style);
166   const context = childDiagnosticContext(child, container, 'absolute');
167   const left = resolveLength(style.left ?? 0, container.width, 'left', context)!;
168   const top = resolveLength(style.top ?? 0, container.height, 'top', context)!;
169   const box = {
170     x: finitePlacement(container.x + left, 'left', left, context),
171     y: finitePlacement(container.y + top, 'top', top, context),
172     width: resolved.borderBox.width,
173     height: resolved.borderBox.height,
174   };
175   return {
176     box,
177     element: childWithUsedSize(
178       child,
179       style,
180       resolved.contentBox.width,
181       resolved.contentBox.height,
182       receiverToken,
183       preparedStyleQuery(prepared),
184     ),
185   };
186 }
187 
188 /** @internal Carries normalized finite content size into the eventual render. */
189 export function childWithUsedSize(
190   child: PibblElement<any>,
191   style: Readonly<SystemStyle>,
192   width: number,
193   height: number,
194   receiverToken?: object,
195   query?: PreparedQuery,
196 ): PibblElement<any> {
197   const renderedChild = clonePibblElement(child);
198   setPlacementConsumed(renderedChild);
199   setPreNormalizedStyle(renderedChild, Object.freeze({
200     ...style,
201     width,
202     height,
203   }), child, receiverToken, query);
204   return renderedChild;
205 }
206 
207 /** @internal Shared by the initial direct-child layout algorithms. */
208 export function resolveDirectChildBox(
209   container: Readonly<LayoutBox>,
210   child: PibblElement<any>,
211   algorithm: string,
212   style: Readonly<SystemStyle> = normalizeDirectChildStyle(child, undefined, container),
213 ): ResolvedBoxStyle {
214   return resolveLayoutBox(
215     style as Readonly<BoxStyle>,
216     {
217       allocation: container,
218       percentageBasis: container,
219       constraints: {
220         minWidth: 0,
221         maxWidth: container.width,
222         minHeight: 0,
223         maxHeight: container.height,
224       },
225       component: child.type.name || 'Anonymous',
226       algorithm: 'render-dispatch',
227     },
228     child.type.name || 'Anonymous',
229     algorithm,
230     true,
231   );
232 }
233 
234 /** @internal Normalizes a descriptor without resolving or invoking its callback. */
235 export function normalizeDirectChildStyle(
236   child: PibblElement<any>,
237   receiverToken?: object,
238   queryBasis?: Readonly<LayoutBox>,
239 ): Readonly<SystemStyle> {
240   return preparedStyleValue(prepareDirectChildStyle(child, receiverToken, queryBasis));
241 }
242 
243 /** Carries responsive eligibility with this normalization, never with a token. */
244 export function prepareDirectChildStyle(
245   child: PibblElement<any>,
246   receiverToken?: object,
247   queryBasis?: Readonly<LayoutBox>,
248 ): Readonly<SystemStyle> | ResponsiveStylePreparation<Readonly<SystemStyle>> {
249   const definition = getPrimitiveDefinition(child.type);
250   const prepared = withReceiverInputProvision(
251     GLOBAL_STATE.renderTransaction,
252     receiverToken,
253     () => resolvePrimitiveStyleInput(
254       (child.props as { readonly style?: unknown }).style,
255       child, queryBasis,
256     ) ?? EMPTY_STYLE,
257   );
258   const style = preparedStyleValue(prepared);
259   const filter = extractSystemFilter(style);
260   const normalized = definition?.normalizeStyle ?
261       definition.normalizeStyle(withoutSystemFilter(style)) :
262       withoutSystemFilter(style);
263   const final = { ...normalized, ...(filter === undefined ? {} : { filter }), ...(style.transition === undefined ? {} : { transition: (style as Readonly<SystemStyle>).transition }) };
264   if (prepared instanceof ResponsiveStylePreparation) {
265     prepared.style = final;
266     return prepared;
267   }
268   return final;
269 }
270 
271 /** @internal Converts source-order descriptors to stable placed children. */
272 export function placeDirectChildren(
273   children: readonly PibblElement<any>[],
274   contentBox: Readonly<LayoutBox>,
275   place: (child: PibblElement<any>) => LayoutBox | {
276     box: LayoutBox;
277     element: PibblElement<any>;
278   },
279   overflow: 'visible' | 'clip',
280 ): PibblElement<any>[] {
281   const occurrences = new Map<Function, number>();
282   const placed: PibblElement<any>[] = [];
283   for (const child of children) {
284     const occurrence = child.key === undefined ?
285       occurrences.get(child.type) ?? 0 :
286       0;
287     if (child.key === undefined) {
288       occurrences.set(child.type, occurrence + 1);
289     }
290     const placement = place(child);
291     const box = 'box' in placement ? placement.box : placement;
292     const element = 'box' in placement ? placement.element : child;
293     placed.push(placeChild({
294       element,
295       box,
296       clipInChildSpace: overflow === 'clip' ? {
297         x: contentBox.x - box.x,
298         y: contentBox.y - box.y,
299         width: contentBox.width,
300         height: contentBox.height,
301       } : undefined,
302       identityHint: createPlacementIdentityHint(child, occurrence),
303     }));
304   }
305   return placed;
306 }
307 
308 /** @internal Prepares one finite direct-child sequence for a layout boundary. */
309 export function materializeLayoutChildren(
310   children: PibblNodeInput,
311   receiver: LayoutReceiver,
312 ): readonly PibblElement<any>[] {
313   // Placement identity owns layout sibling keys. Deferring its check preserves
314   // fail-closed teardown when a later duplicate follows an acquired child.
315   return materializeContainerChildren(children, receiver, {
316     validateKeys: false,
317   });
318 }
319 
320 /** @internal Shares one direct sequence between an occurrence's measurement and paint. */
321 export function prepareLayoutChildren(
322   children: PibblNodeInput,
323   receiver: LayoutReceiver,
324 ): readonly PibblElement<any>[] {
325   const transaction = GLOBAL_STATE.renderTransaction;
326   const receiverToken = GLOBAL_STATE.primitiveReceiverToken;
327   if (!transaction || !receiverToken) {
328     return materializeLayoutChildren(children, receiver);
329   }
330 
331   let receivers = preparedLayoutTransactions.get(transaction);
332   if (!receivers) {
333     receivers = new WeakMap();
334     preparedLayoutTransactions.set(transaction, receivers);
335   }
336   const prepared = receivers.get(receiverToken);
337   if (prepared) return prepared;
338   const materialized = withReceiverInputProvision(
339     transaction,
340     receiverToken,
341     () => materializeLayoutChildren(children, receiver),
342   );
343   receivers.set(receiverToken, materialized);
344   return materialized;
345 }
346 
347 function resolveLayoutBox(
348   style: Readonly<BoxStyle>,
349   context: Readonly<StyleResolutionContext>,
350   component: string,
351   algorithm: string,
352   requireDefinite: boolean,
353 ): ResolvedBoxStyle {
354   if (requireDefinite && (style.width === undefined || style.width === 'auto')) {
355     throw requiredDimension(component, 'width', style.width, context, algorithm);
356   }
357   if (requireDefinite && (style.height === undefined || style.height === 'auto')) {
358     throw requiredDimension(component, 'height', style.height, context, algorithm);
359   }
360 
361   const diagnosticContext = {
362     component,
363     algorithm,
364     constraints: context.constraints,
365   };
366   const width = resolveOptionalAllocationLength(
367     style.width,
368     context.percentageBasis.width,
369     'width',
370     diagnosticContext,
371   );
372   const height = resolveOptionalAllocationLength(
373     style.height,
374     context.percentageBasis.height,
375     'height',
376     diagnosticContext,
377   );
378   const minWidth = resolveOptionalAllocationLength(
379     style.minWidth,
380     context.percentageBasis.width,
381     'minWidth',
382     diagnosticContext,
383   );
384   const maxWidth = resolveOptionalAllocationLength(
385     style.maxWidth,
386     context.percentageBasis.width,
387     'maxWidth',
388     diagnosticContext,
389   );
390   const minHeight = resolveOptionalAllocationLength(
391     style.minHeight,
392     context.percentageBasis.height,
393     'minHeight',
394     diagnosticContext,
395   );
396   const maxHeight = resolveOptionalAllocationLength(
397     style.maxHeight,
398     context.percentageBasis.height,
399     'maxHeight',
400     diagnosticContext,
401   );
402   const padding = normalizeEdges(style.padding, 'padding', diagnosticContext);
403   const allowOverflow = requireDefinite;
404   const maxConstraintWidth = allowOverflow ? allocationCeiling(
405     context.allocation.width,
406     [width, minWidth, maxWidth],
407     padding.left + padding.right,
408     'width',
409     diagnosticContext,
410   ) : context.allocation.width;
411   const maxConstraintHeight = allowOverflow ? allocationCeiling(
412     context.allocation.height,
413     [height, minHeight, maxHeight],
414     padding.top + padding.bottom,
415     'height',
416     diagnosticContext,
417   ) : context.allocation.height;
418 
419   return resolveBox({
420     ...style,
421     width,
422     height,
423     minWidth,
424     maxWidth,
425     minHeight,
426     maxHeight,
427   }, {
428     minWidth: 0,
429     maxWidth: maxConstraintWidth,
430     minHeight: 0,
431     maxHeight: maxConstraintHeight,
432   }, diagnosticContext);
433 }
434 
435 function resolveOptionalAllocationLength(
436   value: BoxStyle['width'],
437   reference: number,
438   property: string,
439   context: Parameters<typeof resolveLength>[3],
440 ): number | undefined {
441   if (value === undefined) return undefined;
442   return resolveLength(value, reference, property, context);
443 }
444 
445 function allocationCeiling(
446   allocation: number,
447   values: readonly (number | undefined)[],
448   padding: number,
449   property: string,
450   context: Parameters<typeof resolveLength>[3],
451 ): number {
452   const ceiling = Math.max(allocation, ...values.filter(
453     (value): value is number => value !== undefined,
454   )) + padding;
455   if (!Number.isFinite(ceiling)) {
456     throw layoutDiagnostic({
457       ...context,
458       property,
459       value: ceiling,
460       reason: 'resolved allocation arithmetic must remain finite',
461     });
462   }
463   return ceiling;
464 }
465 
466 function requiredDimension(
467   component: string,
468   property: 'width' | 'height',
469   value: unknown,
470   context: Readonly<StyleResolutionContext>,
471   algorithm: string,
472 ) {
473   return layoutDiagnostic({
474     component,
475     property,
476     value: value ?? 'auto',
477     algorithm,
478     constraints: context.constraints,
479     reason: 'requires a definite dimension until measurement is available',
480   });
481 }
482 
483 function childDiagnosticContext(
484   child: PibblElement<any>,
485   container: Readonly<LayoutBox>,
486   algorithm: string,
487 ) {
488   return {
489     component: child.type.name || 'Anonymous',
490     algorithm,
491     constraints: {
492       minWidth: 0,
493       maxWidth: container.width,
494       minHeight: 0,
495       maxHeight: container.height,
496     },
497   };
498 }
499 
500 function finitePlacement(
501   resolved: number,
502   property: string,
503   value: unknown,
504   context: ReturnType<typeof childDiagnosticContext>,
505 ): number {
506   if (!Number.isFinite(resolved)) {
507     throw layoutDiagnostic({
508       ...context,
509       property,
510       value,
511       reason: 'resolved placement arithmetic must remain finite',
512     });
513   }
514   return resolved;
515 }
516
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.