# AnchoredLayout

Import from `@pibbl/core/viz`. Supply `items` with unique string/number `key`, local
`anchor`, optional `anchorRadius` (default 0), and numeric outer `width`/`height`.
Additional item fields are preserved and inferred by the children callback.

`direction` defaults to `vertical`: boxes form a column to the right of all
protected anchors, or to their left if that fits. `horizontal` forms a row below
all anchors, or above if that fits. Boxes pack near their anchor coordinates,
with `gap` (default 8) separating boxes and protecting anchors. Bounds default to
the incoming allocation. Items, gap, and explicit bounds can be signals.

`children(item, placement)` renders at the placed box's local origin. Placement
is in the parent's local frame, so connectors can subtract placement.x/y from
the original anchor. The callback cannot call hooks; return a component for hooks.
Stable keys preserve child state. Input order remains paint order, even when
geometric ordering changes. Each child receives its declared box as allocation
and percentage basis. Backgrounds, padding, and pointer behavior are user-owned.

If neither side or the complete stack fits, boxes overflow rather than overlap.
Ancestor clipping still applies. Include borders in declared outer dimensions;
arbitrary overflowing child paint is outside the guarantee. This layout requires
no scales, hover state, or DOM elements.

```tsx
import { Group, Rectangle, Text } from "@pibbl/core";
import { AnchoredLayout } from "@pibbl/core/viz";

export function Annotations() {
  const items = [
    {
      key: "a",
      anchor: { x: 100, y: 100 },
      width: 140,
      height: 40,
      label: "First",
    },
    {
      key: "b",
      anchor: { x: 100, y: 108 },
      width: 140,
      height: 40,
      label: "Second",
    },
  ];
  return (
    <AnchoredLayout items={items} gap={8}>
      {(item) => (
        <>
          <Rectangle
            pointerEvents="none"
            style={{
              width: "100%",
              height: "100%",
              fill: "white",
              cornerRadius: 6,
            }}
          />
          <Group style={{ translateX: 10, translateY: 10 }}>
            <Text pointerEvents="none" style={{ fill: "black" }}>
              {item.label}
            </Text>
          </Group>
        </>
      )}
    </AnchoredLayout>
  );
}
```

Keys use core's `String(key)` normalization; numeric `1` and string `"1"` conflict.
Along the packing axis, items sort by anchor coordinate, with normalized key as
the deterministic tie-breaker. Source order still controls painting. Width,
height, radius, gap, and bounds dimensions must be finite and nonnegative; anchor
and bounds coordinates must be finite. Unrepresentable placement arithmetic
throws before child rendering. Zero-sized boxes are permitted.

Changing a callback or item object preserves a returned component's state when
its key, component type, and tree position stay the same. Signal reads made inside
the callback belong to that item; removing it releases those subscriptions.

## API details from source

<span id="api-AnchoredLayout"></span>

### AnchoredLayout

Arranges keyed Pibbl content together, clear of every supplied anchor.

```ts
AnchoredLayout: <T extends AnchoredItem>(props: AnchoredLayoutProps<T>) => PibblNode
```

Related API: [AnchoredLayout](/reference/components/anchored-layout/), [AnchoredItem](/reference/components/anchored-layout/), [AnchoredLayoutProps](/reference/components/anchored-layout/), [PibblNode](/reference/types/elements-components/#pibblnode).

#### Parameters

- **`props`** — Anchored items, placement constraints, and child renderer. See
[AnchoredLayoutProps](/reference/components/anchored-layout/) .

#### Returns

Pibbl content positioned using the computed placements. See [PibblNode](/reference/types/elements-components/#pibblnode).

#### See also

[AnchoredLayoutProps](/reference/components/anchored-layout/)

[PibblNode](/reference/types/elements-components/#pibblnode)

[AnchoredItem](/reference/components/anchored-layout/)

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:255](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L255)

<span id="api-AnchoredItem"></span>

### AnchoredItem

Declared outer box and protected anchor, all in the parent's local coordinates.

```ts
interface AnchoredItem
```

Related API: [AnchoredItem](/reference/components/anchored-layout/).

#### See also

[AnchoredLayout](/reference/components/anchored-layout/)

[AnchoredLayoutProps](/reference/components/anchored-layout/)

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:20](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L20)

#### Properties and methods

<span id="api-AnchoredItem-key"></span>
<details>
<summary>key</summary>


```ts
readonly key: string | number
```

Stable identity used by the containing protocol. See AnchoredItem.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:22](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L22)

</details>

<span id="api-AnchoredItem-anchor"></span>
<details>
<summary>anchor</summary>


```ts
readonly anchor: Readonly<{ x: number; y: number; }>
```

Logical point to which the content or result is anchored. See AnchoredItem.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:24](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L24)

</details>

<span id="api-AnchoredItem-anchorRadius"></span>
<details>
<summary>anchorRadius (optional)</summary>


```ts
readonly anchorRadius?: number | undefined
```

Clearance around the anchor before placing the item. See AnchoredItem.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:37](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L37)

</details>

<span id="api-AnchoredItem-width"></span>
<details>
<summary>width</summary>


```ts
readonly width: number
```

Horizontal extent in the units of the containing geometry or surface. See AnchoredItem
.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:42](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L42)

</details>

<span id="api-AnchoredItem-height"></span>
<details>
<summary>height</summary>


```ts
readonly height: number
```

Vertical extent in the units of the containing geometry or surface. See AnchoredItem.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:46](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L46)

</details>

<span id="api-AnchoredPlacement"></span>

### AnchoredPlacement

The resolved logical rectangle assigned to an anchored item.

```ts
interface AnchoredPlacement
```

Related API: [AnchoredPlacement](/reference/components/anchored-layout/).

#### See also

[AnchoredLayoutProps](/reference/components/anchored-layout/)

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:53](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L53)

#### Properties and methods

<span id="api-AnchoredPlacement-x"></span>
<details>
<summary>x</summary>


```ts
readonly x: number
```

Horizontal coordinate or displacement in the containing coordinate system. See
AnchoredPlacement.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:58](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L58)

</details>

<span id="api-AnchoredPlacement-y"></span>
<details>
<summary>y</summary>


```ts
readonly y: number
```

Vertical coordinate or displacement in the containing coordinate system. See
AnchoredPlacement.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:63](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L63)

</details>

<span id="api-AnchoredPlacement-width"></span>
<details>
<summary>width</summary>


```ts
readonly width: number
```

Horizontal extent in the units of the containing geometry or surface. See
AnchoredPlacement.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:68](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L68)

</details>

<span id="api-AnchoredPlacement-height"></span>
<details>
<summary>height</summary>


```ts
readonly height: number
```

Vertical extent in the units of the containing geometry or surface. See
AnchoredPlacement.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:73](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L73)

</details>

<span id="api-AnchoredLayoutProps"></span>

### AnchoredLayoutProps

Authored inputs for AnchoredLayout, including the declared data and presentation options.

```ts
interface AnchoredLayoutProps<T extends AnchoredItem>
```

Related API: [AnchoredLayoutProps](/reference/components/anchored-layout/), [AnchoredItem](/reference/components/anchored-layout/).

#### See also

[AnchoredItem](/reference/components/anchored-layout/)

[SignalValue](/reference/types/signal-inputs/#signalvalue)

[AnchoredPlacement](/reference/components/anchored-layout/)

[PibblNode](/reference/types/elements-components/#pibblnode)

[AnchoredLayout](/reference/components/anchored-layout/)

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:84](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L84)

#### Properties and methods

<span id="api-AnchoredLayoutProps-items"></span>
<details>
<summary>items</summary>


```ts
readonly items: SignalValue<readonly T[]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Items to place around their declared anchors. See SignalValue.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:86](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L86)

</details>

<span id="api-AnchoredLayoutProps-direction"></span>
<details>
<summary>direction (optional)</summary>


```ts
readonly direction?: "horizontal" | "vertical" | undefined
```

Direction in which this operation proceeds. See AnchoredLayoutProps.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:88](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L88)

</details>

<span id="api-AnchoredLayoutProps-gap"></span>
<details>
<summary>gap (optional)</summary>


```ts
readonly gap?: SignalValue<number> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Spacing between adjacent items. See SignalValue.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:90](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L90)

</details>

<span id="api-AnchoredLayoutProps-bounds"></span>
<details>
<summary>bounds (optional)</summary>


```ts
readonly bounds?: SignalValue<AnchoredPlacement> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue), [AnchoredPlacement](/reference/components/anchored-layout/).

Logical region constraining the content or query. See SignalValue,
AnchoredPlacement.

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:95](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L95)

</details>

<span id="api-AnchoredLayoutProps-children"></span>
<details>
<summary>children</summary>


```ts
readonly children: (item: T, placement: AnchoredPlacement) => PibblNode
```

Related API: [AnchoredPlacement](/reference/components/anchored-layout/), [PibblNode](/reference/types/elements-components/#pibblnode).

Descendant content or the callback that supplies it. See AnchoredPlacement,
PibblNode.

##### Parameters

- **`item`** — Item being placed.

- **`placement`** — Computed anchor and placement geometry. See [AnchoredPlacement](/reference/components/anchored-layout/).

##### Returns

Pibbl content for that item. See [PibblNode](/reference/types/elements-components/#pibblnode).

[View source — packages/core/src/features/viz/lib/anchored-layout.tsx:103](/source/packages/core/src/features/viz/lib/anchored-layout-tsx/#L103)

</details>

## Implementation guidance for agents

Read the [Drawing, layout, and effects companion](/agents/topics/layout/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Anchored callouts](/minimal-examples/viz/anchored/): Arrange labeled callouts while clearing their anchor points. [Plain source](/minimal/viz/anchored.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.