ShelfWidgetLayoutTraits

struct ShelfWidgetLayoutTraits

These replace the per-widget width tables Droppy used to hardcode. The shelf owns the single layout algorithm; the widget only supplies numbers. The width fields remain optional solely for source and binary compatibility, but current Droppy hosts admit a descriptor only when both are explicit. nil never selects a host geometry fallback; the descriptor is refused.

Every number here is the widget's RECTANGLE, in points at the Regular shelf size: the area makeWidgetView(_:context:) draws in, which is what availableSize reports back and what the harness renders. The shelf adds its own chrome around it (the slot inset, the side insets, the cutout clearance), and the Enlarged shelf size scales the rectangle with everything else. See DroppyShellMetrics for the chrome. The metrics call the rectangle the card; nothing is drawn around it. Droppy paints no fill or border behind a widget, and a droplet should not either. See Design guidelines.

Initializers

init(preferredSoloWidth:preferredPairedWidth:pairWeight:minimumWidth:contentHeight:)

init(preferredSoloWidth: CGFloat? = nil, preferredPairedWidth: CGFloat? = nil, pairWeight: Double = 1, minimumWidth: CGFloat? = nil, contentHeight: ShelfWidgetContentHeight = .standard)

Creates layout traits.

The optional width defaults preserve existing source and binary call sites, but they do not create a host-layout fallback. A current Droppy host refuses a widget descriptor unless both preferredSoloWidth and preferredPairedWidth are explicit. minimumWidth and contentHeight retain their ordinary host defaults.

init(preferredSoloWidth:preferredPairedWidth:pairWeight:minimumWidth:contentHeight:notchWrap:)

init(preferredSoloWidth: CGFloat? = nil, preferredPairedWidth: CGFloat? = nil, pairWeight: Double = 1, minimumWidth: CGFloat? = nil, contentHeight: ShelfWidgetContentHeight = .standard, notchWrap: ShelfWidgetNotchWrapTraits?)

Creates traits that opt in to the notch wrap (1.21.0).

The same fields as the initializer above, plus notchWrap. A droplet that calls this declares minAPI 1.21.0.

Properties

contentHeight

let contentHeight: ShelfWidgetContentHeight

Card height request. See ShelfWidgetContentHeight.

minimumWidth

let minimumWidth: CGFloat?

Hard minimum width of the card in points. The shelf never lays the widget out narrower than this in a grouped row. nil uses the shelf's floor.

notchWrap

let notchWrap: ShelfWidgetNotchWrapTraits?

Opt-in to wrapping the widget's header row around the camera on a notched Mac (ShelfWidgetNotchWrapTraits), or nil to keep the classic layout everywhere. Added in 1.21.0; every widget built before it, and every widget that leaves this nil, never wraps.

pairWeight

let pairWeight: Double

Relative weight when the shelf splits space across a grouped row. 1 is an even share. The compatibility name "pair" applies to every row containing two to four widgets.

preferredPairedWidth

let preferredPairedWidth: CGFloat?

Preferred width of the card in points when the widget shares a row with one to three other widgets. The compatibility name "paired" means every grouped row (2...4), not only exactly two widgets. The row splits its width by pairWeight and floors each card at minimumWidth, so this is a preference, not a guarantee.

This remains optional for source and binary compatibility. Current Droppy hosts refuse a descriptor whose grouped width is nil; nil does not use a standard grouped-width fallback.

preferredSoloWidth

let preferredSoloWidth: CGFloat?

Preferred width of the card in points when the widget is shown alone.

The shell opens to the card plus its chrome, and never narrower than shelfMinimumWidth(usesNotchStyle:): a card that declares less than shelfMinimumSoloCardWidth(usesNotchStyle:) is stretched to it rather than centred in a shell that stays wide.

This remains optional for source and binary compatibility. Current Droppy hosts refuse a descriptor whose solo width is nil; nil does not use a standard solo-width fallback.