Shared Swift foundations

iOS overview · Integration

These contracts apply to the native Calendar and resource Timeline. Web APIs and lifecycle behavior are documented separately; platform APIs are not interchangeable.

Dates and intervals

• CivilDate is a Gregorian date in YYYY-MM-DD format, within years 1...9999. It is neither an instant nor a zoned timestamp.
• LocalDateTime is a floating local value in YYYY-MM-DDTHH:mm format. Seconds, offsets, invalid dates and 24:00 are rejected. No time-zone or DST conversion occurs.
• Intervals have exclusive ends strictly after their starts. An all-day interval from September 8 to September 10 occupies September 8 and 9. A timed end at midnight does not occupy the following day.
• Supply today's civil date according to your app's clock and time-zone policy. Refresh it in your app when required; the library does not own your clock.

Model lifetime and confirmed data

Retain one CalendarModel or TimelineModel per component instance on the main actor, for example in consumer-owned @State. Do not recreate models on each SwiftUI body evaluation. Handle throwing initialization at your app's composition boundary and show an appropriate error if input is invalid.

Your app owns authoritative data, forms, validation and persistence. Views own transient previews and emit typed requests; a gesture does not save data itself. Validate a request against your current data, reject stale originals and supply a confirmed snapshot through setEvents or setData. Ignoring a request leaves the confirmed display unchanged. An omitted gesture callback disables that edit.

Calendar and Timeline have distinct request types. In particular, TimelineData.applying validates the original entry and assignment before returning a replacement snapshot. See each component guide for its exact confirmation flow. There is no library-owned asynchronous edit-save or persistence protocol. Timeline read loading has its own provider lifecycle.

Presentation and accessibility

SwiftUI appearance and Dynamic Type drive the native presentation. Calendar supports .tint(...); Web CSS classes and theme variables do not apply to SwiftUI. German and English controls are implemented. Accessibility text sizes use readable list presentations, with details and consumer forms as alternatives to small grips. A complete VoiceOver audit and physical touch/haptic acceptance remain outstanding.

Haptic feedback

Calendar Day/Week timed movement and Timeline editing use a soft activation pulse after a recognized long press and selection ticks when the snapped target changes (calendar raster steps or scale-dependent Timeline steps). Rapid movement is limited to one tick per 80 ms, with no delayed replay. Cancel and unchanged drops are silent. Set hapticsEnabled: false on CalendarView or TimelineView to disable that component's interaction feedback. Native controls retain their own system behavior.

Consumers can retain a CalendarHaptics instance for the same feedback vocabulary. Call success() only after accepting an update, and failure() when rejecting a user action. Set its isEnabled property to disable consumer feedback as well. beginInteraction(step:), updateInteraction(step:) and endInteraction() support other custom interactions; the components already call them for their own editing gestures. The demo confirms changes in memory, with no persistence guarantee. Haptics are optional and never replace visible state or validation messages.

Calendar long press emits one short soft impulse when the editing/movement mode activates, including a stationary hold. Moving through raster steps uses separate selection ticks; repeated updates do not repeat the activation impulse.

Timed Calendar events emit hold activation feedback when the long press is recognized, before the finger moves. Timed Day/Week cards and all-day Week bars use the native hold-began trigger. Moving the finger before hold recognition scrolls the surrounding grid, including when the gesture starts on an event.