AnchoredLayout

Read as Markdown

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.

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

AnchoredLayout

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

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

Parameters

props — Anchored items, placement constraints, and child renderer. See AnchoredLayoutProps .

Returns

Pibbl content positioned using the computed placements. See PibblNode.

AnchoredItem

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

interface AnchoredItem

Related API: AnchoredItem.

Properties and methods

key

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

anchor

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

anchorRadius (optional)

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

width

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

height

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

AnchoredPlacement

The resolved logical rectangle assigned to an anchored item.

interface AnchoredPlacement

Related API: AnchoredPlacement.

Properties and methods

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

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

width

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

height

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

AnchoredLayoutProps

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

interface AnchoredLayoutProps<T extends AnchoredItem>

Related API: AnchoredLayoutProps, AnchoredItem.

Properties and methods

items

readonly items: SignalValue<readonly T[]>

Related API: SignalValue.

Items to place around their declared anchors. See SignalValue.

View source — packages/core/src/features/viz/lib/anchored-layout.tsx:86

direction (optional)

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

gap (optional)

readonly gap?: SignalValue<number> | undefined

Related API: SignalValue.

Spacing between adjacent items. See SignalValue.

View source — packages/core/src/features/viz/lib/anchored-layout.tsx:90

bounds (optional)

readonly bounds?: SignalValue<AnchoredPlacement> | undefined

Related API: SignalValue, AnchoredPlacement.

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

View source — packages/core/src/features/viz/lib/anchored-layout.tsx:95

children

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

Related API: AnchoredPlacement, 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.

Returns

Pibbl content for that item. See PibblNode.

View source — packages/core/src/features/viz/lib/anchored-layout.tsx:103

Implementation guidance for agents

Read the Drawing, layout, and effects companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Anchored callouts: Arrange labeled callouts while clearing their anchor points. Plain source

Documentation version

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

AnchoredLayout

API details from source

AnchoredLayout

Parameters

Returns

See also

AnchoredItem

See also

Properties and methods

AnchoredPlacement

See also

Properties and methods

AnchoredLayoutProps

See also

Properties and methods

Parameters

Returns

Implementation guidance for agents

Complete minimal examples

Documentation version