# packages/core/src/features/viz/lib/anchored-layout.tsx 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/features/viz/lib/anchored-layout.tsx#L255). [Back to reference](/reference/components/anchored-layout/)
1 import {
2   Group,
3   resolveSignalValue,
4   useLayoutBox,
5   type PibblNode,
6   type SignalValue,
7 } from "@pibbl/core";
8 import {
9   pushLayoutBox,
10   setCurrentComponentAfterRender,
11   withHooksForbidden,
12 } from "@pibbl/core/internal";
13 
14 /**
15  * Declared outer box and protected anchor, all in the parent's local coordinates.
16  *
17  * @see {@link AnchoredLayout}
18  * @see {@link AnchoredLayoutProps}
19  */
20 export interface AnchoredItem {
21   /** Stable identity used by the containing protocol. See {@link AnchoredItem}. */
22   readonly key: string | number;
23   /** Logical point to which the content or result is anchored. See {@link AnchoredItem}. */
24   readonly anchor: Readonly<{
25     /**
26      * Horizontal coordinate or displacement in the containing coordinate system. See
27      * {@link AnchoredItem}.
28      */
29     x: number;
30     /**
31      * Vertical coordinate or displacement in the containing coordinate system. See
32      * {@link AnchoredItem}.
33      */
34     y: number;
35   }>;
36   /** Clearance around the anchor before placing the item. See {@link AnchoredItem}. */
37   readonly anchorRadius?: number;
38   /**
39    * Horizontal extent in the units of the containing geometry or surface. See {@link AnchoredItem}
40    * .
41    */
42   readonly width: number;
43   /**
44    * Vertical extent in the units of the containing geometry or surface. See {@link AnchoredItem}.
45    */
46   readonly height: number;
47 }
48 /**
49  * The resolved logical rectangle assigned to an anchored item.
50  *
51  * @see {@link AnchoredLayoutProps}
52  */
53 export interface AnchoredPlacement {
54   /**
55    * Horizontal coordinate or displacement in the containing coordinate system. See
56    * {@link AnchoredPlacement}.
57    */
58   readonly x: number;
59   /**
60    * Vertical coordinate or displacement in the containing coordinate system. See
61    * {@link AnchoredPlacement}.
62    */
63   readonly y: number;
64   /**
65    * Horizontal extent in the units of the containing geometry or surface. See
66    * {@link AnchoredPlacement}.
67    */
68   readonly width: number;
69   /**
70    * Vertical extent in the units of the containing geometry or surface. See
71    * {@link AnchoredPlacement}.
72    */
73   readonly height: number;
74 }
75 /**
76  * Authored inputs for AnchoredLayout, including the declared data and presentation options.
77  *
78  * @see {@link AnchoredItem}
79  * @see {@link SignalValue}
80  * @see {@link AnchoredPlacement}
81  * @see {@link PibblNode}
82  * @see {@link AnchoredLayout}
83  */
84 export interface AnchoredLayoutProps<T extends AnchoredItem> {
85   /** Items to place around their declared anchors. See {@link SignalValue}. */
86   readonly items: SignalValue<readonly T[]>;
87   /** Direction in which this operation proceeds. See {@link AnchoredLayoutProps}. */
88   readonly direction?: "vertical" | "horizontal";
89   /** Spacing between adjacent items. See {@link SignalValue}. */
90   readonly gap?: SignalValue<number>;
91   /**
92    * Logical region constraining the content or query. See {@link SignalValue},
93    * {@link AnchoredPlacement}.
94    */
95   readonly bounds?: SignalValue<AnchoredPlacement>;
96   /**
97    * Descendant content or the callback that supplies it. See {@link AnchoredPlacement},
98    * {@link PibblNode}.
99    * @param item - Item being placed.
100    * @param placement - Computed anchor and placement geometry. See {@link AnchoredPlacement}.
101    * @returns Pibbl content for that item. See {@link PibblNode}.
102    */
103   readonly children: (item: T, placement: AnchoredPlacement) => PibblNode;
104 }
105 function finite(value: number, name: string, nonnegative = false) {
106   if (!Number.isFinite(value) || (nonnegative && value < 0))
107     throw new RangeError(
108       `AnchoredLayout ${name} must be finite${nonnegative ? " and nonnegative" : ""}.`,
109     );
110   return value;
111 }
112 function arrange(
113   items: readonly AnchoredItem[],
114   bounds: AnchoredPlacement,
115   gap: number,
116   vertical: boolean,
117 ): AnchoredPlacement[] {
118   finite(gap, "gap", true);
119   finite(bounds.x, "bounds.x");
120   finite(bounds.y, "bounds.y");
121   finite(bounds.width, "bounds.width", true);
122   finite(bounds.height, "bounds.height", true);
123   finite(bounds.x + bounds.width, "bounds right");
124   finite(bounds.y + bounds.height, "bounds bottom");
125   const keys = new Set<string>();
126   const rows = items.map((item, index) => {
127     if (typeof item.key !== "string" && typeof item.key !== "number")
128       throw new TypeError("AnchoredLayout keys must be strings or numbers.");
129     const key = String(item.key);
130     if (keys.has(key))
131       throw new Error(`AnchoredLayout duplicate key "${key}".`);
132     keys.add(key);
133     finite(item.anchor.x, "anchor.x");
134     finite(item.anchor.y, "anchor.y");
135     finite(item.width, "width", true);
136     finite(item.height, "height", true);
137     const radius = finite(item.anchorRadius ?? 0, "anchorRadius", true);
138     return {
139       item,
140       index,
141       key,
142       radius,
143       along: vertical ? item.anchor.y : item.anchor.x,
144       across: vertical ? item.anchor.x : item.anchor.y,
145       size: vertical ? item.height : item.width,
146       breadth: vertical ? item.width : item.height,
147       position: 0,
148     };
149   });
150   if (!rows.length) return [];
151   // Sort a private working list; preserve source paint order when rendering.
152   rows.sort(
153     (a, b) => a.along - b.along || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0),
154   );
155   const start = vertical ? bounds.y : bounds.x;
156   const end = finite(
157     start + (vertical ? bounds.height : bounds.width),
158     "packing end",
159   );
160   const acrossStart = vertical ? bounds.x : bounds.y;
161   const acrossEnd = finite(
162     acrossStart + (vertical ? bounds.width : bounds.height),
163     "cross-axis end",
164   );
165   let positive = -Infinity,
166     negative = Infinity,
167     breadth = 0,
168     cursor = start;
169   for (const row of rows) {
170     positive = Math.max(
171       positive,
172       finite(row.across + row.radius + gap, "anchor clearance"),
173     );
174     negative = Math.min(
175       negative,
176       finite(row.across - row.radius - gap, "anchor clearance"),
177     );
178     breadth = Math.max(breadth, row.breadth);
179     row.position = Math.max(start, row.along - row.size / 2, cursor);
180     cursor = finite(row.position + row.size + gap, "packing position");
181   }
182   // Back-pack at the far edge, then preserve separation by overflowing if needed.
183   let limit = end;
184   for (let i = rows.length - 1; i >= 0; i--) {
185     const row = rows[i];
186     row.position = Math.min(row.position, limit - row.size);
187     limit = finite(row.position - gap, "packing limit");
188   }
189   const shift = Math.max(0, start - rows[0].position);
190   const positiveFits =
191     positive >= acrossStart && positive + breadth <= acrossEnd;
192   const negativeFits =
193     negative - breadth >= acrossStart && negative <= acrossEnd;
194   const usePositive = positiveFits || !negativeFits;
195   const placements: AnchoredPlacement[] = new Array(items.length);
196   for (const row of rows) {
197     const along = finite(row.position + shift, "placement");
198     const across = finite(
199       usePositive ? positive : negative - row.breadth,
200       "placement",
201     );
202     const x = vertical ? across : along,
203       y = vertical ? along : across;
204     finite(x + row.item.width, "placement right");
205     finite(y + row.item.height, "placement bottom");
206     placements[row.index] = {
207       x,
208       y,
209       width: row.item.width,
210       height: row.item.height,
211     };
212   }
213   return placements;
214 }
215 function Item<T extends AnchoredItem>({
216   item,
217   placement,
218   render,
219 }: {
220   item: T;
221   placement: AnchoredPlacement;
222   render: AnchoredLayoutProps<T>["children"];
223 }): PibblNode {
224   const box = { x: 0, y: 0, width: placement.width, height: placement.height };
225   // Both the received allocation and percentage basis belong to the declared box.
226   const outer = pushLayoutBox(box);
227   let inner: (() => void) | undefined;
228   try {
229     inner = pushLayoutBox(box);
230     setCurrentComponentAfterRender(() => {
231       inner!();
232       outer();
233     });
234   } catch (error) {
235     inner?.();
236     outer();
237     throw error;
238   }
239   return withHooksForbidden(
240     "Pibbl hooks cannot be called in AnchoredLayout children; return a component instead.",
241     () => render(item, placement),
242   );
243 }
244 /**
245  * Arranges keyed Pibbl content together, clear of every supplied anchor.
246  *
247  * @param props - Anchored items, placement constraints, and child renderer. See
248  * {@link AnchoredLayoutProps} .
249  * @returns Pibbl content positioned using the computed placements. See {@link PibblNode}.
250  *
251  * @see {@link AnchoredLayoutProps}
252  * @see {@link PibblNode}
253  * @see {@link AnchoredItem}
254  */
255 export function AnchoredLayout<T extends AnchoredItem>(
256   props: AnchoredLayoutProps<T>,
257 ): PibblNode {
258   const allocation = useLayoutBox();
259   const items = resolveSignalValue(props.items);
260   if (!Array.isArray(items))
261     throw new TypeError("AnchoredLayout items must be an array.");
262   if (typeof props.children !== "function")
263     throw new TypeError(
264       "AnchoredLayout children must be a synchronous function.",
265     );
266   const direction = props.direction ?? "vertical";
267   if (direction !== "vertical" && direction !== "horizontal")
268     throw new TypeError(
269       "AnchoredLayout direction must be vertical or horizontal.",
270     );
271   const bounds =
272     props.bounds === undefined
273       ? { x: 0, y: 0, width: allocation.width, height: allocation.height }
274       : resolveSignalValue(props.bounds);
275   const placements = arrange(
276     items,
277     bounds,
278     resolveSignalValue(props.gap ?? 8),
279     direction === "vertical",
280   );
281   return items.map((item, i) => (
282     <Group
283       key={String(item.key)}
284       style={{ translateX: placements[i].x, translateY: placements[i].y }}
285     >
286       <Item item={item} placement={placements[i]} render={props.children} />
287     </Group>
288   ));
289 }
290
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.