API reference
Every public type in DroppyKit, 123 of them, grouped by what they are for.
Read straight from the compiler’s symbol graph, so a type that is not on this page is not in the module.
The droplet
What every droplet is built out of.
DropletThe runtime object representing one droplet inside the host process.
DropletIDStable identifier of a droplet across the whole system.
DropletHostEverything the host offers a droplet.
Shelf widgets
A card on the expanded shelf, alone or sharing the row.
ShelfWidgetProvidingAdopt to contribute one or more widgets to the notch shelf.
ShelfWidgetDynamicLayoutProvidingOptional live-layout refinement for a shelf widget provider.
ShelfWidgetDescriptorStatic description of one shelf widget, rendered by the host without calling into the widget's views.
ShelfWidgetContextContext passed to widget view factories on every mount.
ShelfWidgetIDStable identifier of one shelf widget a droplet provides.
ShelfWidgetLayoutTraitsDeclarative layout parameters for one shelf widget.
ShelfWidgetContentHeightHow tall the widget's content area should be inside the shelf.
ShelfWidgetFocusPolicyWhether the widget participates in shelf keyboard focus.
ShelfWidgetPlacementA widget's horizontal position within its shelf row.
ShelfWidgetPrewarmPolicyWhether the shelf may mount the widget invisibly ahead of time.
Live activities
A compact row beside the notch, and its detail.
LiveActivityProvidingAdopt to show a compact live activity in the notch or island: small leading and trailing accessories beside the (simulated) notch, and an expanded surface on hover or tap.
LiveActivityStateState of a droplet's compact live activity.
LiveActivityContextStructure
LiveActivityPresentationStateContext passed to makeExpanded(context:).
CompactLiveActivityContextContext passed to the seat-aware compact factories (DroppyKit 0.7.0).
CompactLiveActivityPresentationMetadataOpaque host-facing metadata for a compact live activity's leading accessory.
Expanded surfaces
A takeover on the notch.
ExpandedSurfaceProvidingA provider of expanded surfaces: content, size, and the far end of the host's lifecycle.
ExpandedSurfaceHostingAdopt to take the expanded shelf over with your own content.
ExpandedSurfaceDescriptorStatic description of one expanded surface, readable by the host without mounting anything.
ExpandedSurfaceContextWhat the host tells expanded-surface content about its mount.
ExpandedSurfaceIDStable identifier of one expanded surface a droplet provides.
ExpandedSurfacePresentationOne live presentation of an expanded surface, as the host records it.
ExpandedSurfacePresentationRequestA request to take the expanded shelf over with one of your surfaces.
ExpandedSurfaceSizeProposalWhat the host offers before asking a droplet how big its surface wants to be.
ExpandedSurfaceHostSuppressionWhich of the host's own expanded-shelf behaviors stand down while a takeover is on screen.
ExpandedSurfaceDismissalReasonWhy an expanded surface stopped being presented.
Other surfaces
Settings, the lock screen, the menu bar, HUDs.
SettingsPaneProvidingAdopt to contribute a settings pane to the Droplets shop detail page and to embedded settings surfaces.
SettingsPaneContextContext passed to makeSettingsPane(context:).
SettingsPanePresentationWhere a settings pane is being presented.
HUDPresentingMarker capability for droplets that present transient HUDs.
LockScreenStatusProvidingAdopt to publish a status entry on Droppy's lock screen surface.
LockScreenStatusEntryOne entry in the lock screen status widget strip.
MenuBarExtraProvidingAdopt to contribute a menu bar extra.
MenuBarExtraDescriptorStatic description of a menu bar extra a droplet contributes.
DropletSurfaceKindThe kind of surface a droplet view is currently rendered on.
Host services
Everything a droplet can ask Droppy to do.
DropletPreferencesServicePersistent, droplet-scoped settings.
DropletEnvironmentServiceRead-only facts about the host and the machine it is running on.
DropletHUDServicePresents transient HUDs on the notch surface.
DropletHUDRequestA transient HUD to show in the notch.
DropletHUDPriorityHow loudly a HUD asks for attention.
DropletShelfServiceOpens and closes Droppy's shelf, and reveals this droplet's widgets in it.
DropletLiveActivityServiceDrives this droplet's live activity.
DropletLiveActivitySeatWhere a droplet's activity currently sits (DroppyKit 0.6.0).
DropletLiveActivityYieldReasonWhy a droplet's activity is not holding the compact slot (DroppyKit 0.6.0).
DropletNotchSurfaceServicePresents and dismisses expanded (takeover) surfaces on the notch.
DropletShortcutsServiceRegisters global keyboard shortcuts the user can rebind in Droppy's Settings, Shortcuts page.
DropletKeyboardShortcutA key equivalent, as the user recorded it.
DropletWorkspaceServiceThings a droplet can ask the system to do on the user's behalf.
DropletFeedbackServicePlays Droppy's own sound and haptic feedback, so a droplet feels like the rest of the app instead of inventing its own vocabulary.
DropletFeedbackCueOne of the host's own feedback cues.
DropletPermissionsServiceChecks and requests the macOS permissions behind a capability.
DropletPermissionStatusWhether the host currently holds a system permission.
DropletInstallStateServiceReports what the user has switched on, so a droplet can avoid doing work for a widget nobody is showing.
DropletInstallStateWhich of this droplet's pieces the user currently has switched on.
DropletLogServiceWrites into Droppy's own log stream, tagged with the droplet id.
DropletLogLevelSeverity of a droplet log line.
DropletNotchGeometryHow the notch surface is physically shaped on one display.
DropletExpandedShelfStateWhat the host's expanded shelf is currently showing.
DropletSurfaceAppearanceThe appearance Droppy is drawing its surfaces in.
DroppyKitHostBridgeExtension points a host process installs into DroppyKit at launch.
Manifest and bundle
What ships, and what the host reads before it loads.
DropletManifestThe contents of a droplet's droplet.json.
DropletManifestErrorWhy a droplet.json was refused.
DropletCreatorWho made a droplet.
DropletCreatorAvatarThe rules a creator avatar has to satisfy.
DropletSourceWhere a droplet's source lives.
DropletSurfaceA surface a droplet says it provides.
DropletKitRequirementWhich DroppyKit a droplet was built against.
DropletPermissionCapability strings a .droplet declares under DroppyPermissions in its Info.plist.
DropletIconThe rules a droplet's icon has to satisfy.
DropletIconErrorWhy an Icon Composer document was refused.
DropletIconValidationChecks an Icon Composer document without rendering it.
DropletBundleInfoParsed metadata of one .droplet bundle, read from its Info.plist without loading any code.
DropletBundleInfoErrorErrors thrown while reading a .droplet's metadata.
DropletInfoPlistKeyInfo.plist keys of a .droplet bundle.
Design system
Droppy's own tokens, rows and controls.
AdaptiveColorsSemantic color palette for droplet UI.
DroppySpacingStandardized spacing values on a 4pt grid.
DroppyRadiusStandardized corner radius values (tiered radii standard).
DroppyOpacityStandardized opacity values for consistent layering.
DroppyAnimationDroppy's named animation presets.
DroppyLiveActivityMetricsNative metrics for compact and interactive live-activity rows.
DroppySettingsControlMetricsShared metric constants for settings rows.
DroppySettingsLayoutMetricsShared layout metrics for settings rows and cards.
DroppyAccentButtonStyleFilled accent pill for primary actions.
DroppyQuietButtonStyleQuiet neutral pill for secondary actions.
DroppyCircleButtonStyleCircular icon button for icon-only actions (close, back, inline glyph actions) on settings-style surfaces.
DroppyButtonChromeNeutral chrome fill shared by Droppy's quiet filled control family.
DroppyButtonSizeSize variants of the Droppy button family.
DroppyLiveActivityControlStyleA 24pt circular control matching Droppy's collapsed media interaction.
DroppyLiveActivityControlProminenceVisual prominence for an inline live-activity control.
DropletSettingsCardCard wrapper for grouping settings rows.
DropletSettingsDividerDivider between rows inside a DropletSettingsCard.
DropletControlRowBase settings row: title with optional icon and info tip on the left, any accessory control on the right.
DropletToggleRowStandard toggle row: title and info tip on the left, small switch on the right.
DropletMiniToggleRowCompact nested toggle row for stacked rules and reorder lists.
DropletStackedRowRow whose content stacks beneath the title block instead of trailing on the right.
DropletSliderRowStandard slider row: label and value pill on top, full-width slider below.
DropletGroupedPickerRowGrouped picker row used inside DropletSettingsCard when the picker should extend to the card's edges.
DropletValuePillShared capsule pill for compact read-only values in settings rows.
SettingsUnifiedSegmentedRowFull-width segmented control whose outer corners follow the enclosing card's curvature.
SettingsPickerOptionOne option of a segmented settings picker.
SettingsGroupPositionVertical position of a grouped row within its parent DropletSettingsCard.
SettingsSelectionChromeOne rule for "this is the option you picked", across every selectable control DroppyKit publishes.
SettingsAdaptiveColorBuilds a Color that resolves per appearance, so a token can be written as a (ColorScheme) -> Color function and still be read at a call site with no ColorScheme in scope.
SettingsInfoTipLightweight info button that shows a text popover on hover.
SettingsSearchEntryOne entry the host's settings search can surface for a droplet.
GroupedCornersDescribes which corners of a cell round when composing grouped rows, where outer corners follow the parent card's curvature and inner edges stay flat.
DroppyKitThemeBridgeEnumeration
DroppyKitThemeResolutionHost-installed theme hooks.
DroppyMarkdownEditorDroppy's markdown editing surface.
DroppyMarkdownEditorCommandsA handle onto the host editor's command bus (DroppyKit 0.2.2).
DroppyMarkdownEditorContextEverything the host editor needs beyond the text binding (DroppyKit 0.2.2).
DroppyMarkdownHighlightColorMarker-pen palette for ==highlight== spans (DroppyKit 0.2.2).
DroppyMarkdownToolbarActionA formatting command a droplet's toolbar can send to the host editor (DroppyKit 0.2.2).
settingsSectionHeader(_:)Single source of truth for the 13pt semibold section headers that sit above settings cards.
settingsUnifiedSegmentLabel(icon:title:isSelected:isEnabled:)Canonical icon and title label used inside segmented picker tiles.
settingsUnifiedPickerRow(title:subtitle:icon:iconColor:options:accessibilityLabel:groupPosition:isEnabled:isSelected:action:content:)The canonical picker row: title block over an edge-to-edge segmented control inside a DropletSettingsCard.
Versioning
The handshake between a droplet and its host.