ShelfWidgetContext

struct ShelfWidgetContext

Initializers

init(availableSize:isPaired:isShelfTransitioning:isPreview:surface:)

init(availableSize: CGSize, isPaired: Bool = false, isShelfTransitioning: Bool = false, isPreview: Bool = false, surface: DropletSurfaceKind = .builtInNotch)

Creates a context. Constructed by hosts, read by droplets.

init(availableSize:isPaired:placement:isCompact:isShelfTransitioning:isPreview:surface:usesIslandCurvature:usesAdaptiveForegrounds:)

init(availableSize: CGSize, isPaired: Bool, placement: ShelfWidgetPlacement, isCompact: Bool, isShelfTransitioning: Bool, isPreview: Bool, surface: DropletSurfaceKind, usesIslandCurvature: Bool, usesAdaptiveForegrounds: Bool)

Creates a context with the complete host-owned presentation facts. The legacy initializer above remains intact for already compiled droplets and older source clients.

Properties

availableSize

let availableSize: CGSize

The host-owned layout size for this widget mount.

A shelf host MUST provide its settled slot width in width before it calls makeWidgetView(_:context:). A zero height means this host has no single stable height for the mount; widgets use their declared contentHeight rather than infer height from an animated frame.

isCompact

let isCompact: Bool

Whether the host requested the widget's compact composition.

Every grouped row (2...4 widgets) is compact. A host may also choose a compact composition for a solo variant, but it must never hand a grouped widget a full-density context; use placement for the leading, middle, or trailing distinction within that grouped row.

isPaired

let isPaired: Bool

True when the widget shares its row with one to three other widgets. This compatibility property is true for every grouped row (2...4). Use placement to distinguish leading, middle, and trailing slots, and isCompact to select the grouped visual composition.

isPreview

let isPreview: Bool

True when the view is mounted in a non-interactive preview (settings mockups, the harness screenshot mode). Skip side effects.

isShelfTransitioning

let isShelfTransitioning: Bool

True while the shelf itself is animating open or closed. Freeze expensive live content while this is true; the shelf's springs must never compete with widget-internal animation.

placement

let placement: ShelfWidgetPlacement

The widget's exact row placement. In a three-or-four-widget row, an inner card receives .middle; use this rather than treating every grouped widget as a leading or trailing peer.

surface

let surface: DropletSurfaceKind

The surface kind hosting the widget.

usesAdaptiveForegrounds

let usesAdaptiveForegrounds: Bool

Whether the shelf is drawn over a transparent notch material and the product should select adaptive foreground colors.

usesIslandCurvature

let usesIslandCurvature: Bool

Whether a solo card sits inside the dynamic-island curvature. Products use this only for internal edge clearance; the host remains the owner of the outer clip.