z-cal

    Agent integration guide

    Documentation index

    Use this route when integrating z-cal into a consumer application. For changes to z-cal itself, start with Contributing.

    Integration sequence

    1. Check the installed version in the consumer's lockfile/package metadata. Use the matching repository tag or installed declarations when its API differs from main.
    2. Read installation, then choose the vanilla or React quickstart. Install z-cal; React bindings are z-cal/react with React 19 peers.
    3. Read configuration for the selected view, its required plugin, timezone, container sizing, and optional resources. Specify view explicitly.
    4. Read events before wiring data sources or mutations. Decide who owns event data: application state, the instance's local store, or a remote source with persisted writes.
    5. For React, read props and lifecycle before adding refs, controller hooks, or slots. Keep unchanged event arrays stable; remount to change plugins.
    6. Verify the integration in the consumer: the calendar is styled, the intended view renders, example events appear at the expected time, and enabled interactions behave correctly.

    API facts that prevent common mistakes

    • createCalendar(host, { plugins, options }); React takes options directly as props.
    • height is a CSS string. Percentage sizing needs a defined parent and host height.
    • Interaction plus selectable enables selection; your application creates the event/form.
    • Interaction plus editable enables event dragging/resizing, subject to event overrides.
    • businessHours shades closed time; edits are only limited when dragConstraint, resizeConstraint, or selectConstraint is 'businessHours' (or inline hours, an event id, or a predicate). eventOverlap: false / selectOverlap: false block overlapping edits and selections.
    • Dates returned by the API are Temporal values. All-day ends are exclusive.
    • updateEvent replaces the complete event input and requires id and start.
    • Recurring events need the Recurrence plugin. Pass the rule as recurrence: { rrule } (RFC 5545 text) or object fields; do not pre-expand. Callbacks report occurrences with event.occurrence (seriesId, key, index); a drop already recorded an override, and editRecurringEvent(series, event, scope) returns the inputs to write back for a chosen scope.
    • Source refetches can replace local edits; persist before refetching. Replacing an events prop can do the same. Stable IDs preserve identity, not persistence.
    • responsiveWeek is opt-in and only affects timeGridWeek and views derived from it.
    • keyboardNavigation (arrow keys across cells, Enter, Shift+Arrow selection) and keyboardShortcuts (t, j/k, d/w/m/a) are opt-in; enable them when the app needs grid-level keyboard access.
    • Popovers, inspectors, and selection UI belong to the application. Anchor them with getEventElements(id) and decide dismissal from pointerDown (target is 'event', 'date', or 'none'; consume() makes a press that only dismisses do nothing else); do not query or stamp the calendar's DOM to recover what it rendered.
    • Custom content replaces that content region. Initials are not generated; add icons through renderers.
    • Plain strings are text. { html } is trusted markup; use safe text/DOM/React content for untrusted data.

    What the library owns and what the application owns

    The engine owns the DOM nodes it creates and their identity, hit-testing and geometry, and gesture facts such as what was pressed and what is in flight. The application owns what a press means for its UI, how its data model maps onto events, and its popover or dialog library. When something the calendar knew at render time is only recoverable by querying its DOM (closest, querySelector, stamping attributes), that is a gap to report against z-cal rather than to work around; deciding what to do with such a fact stays in the application.

    Resolve uncertainty

    Consult API reference for methods, exports, and callback contracts, then the source pointers there for exact option types and defaults. Prefer z-cal's declarations over APIs from another calendar library. Consult troubleshooting for missing views, stale props, Temporal errors, and layout issues. Solid and Svelte adapters are currently unavailable.

    Completion checks

    • The consumer's typecheck and build pass with actual z-cal imports.
    • CSS and Temporal initialization are loaded where required.
    • The view's plugin is registered and the container has usable dimensions.
    • A known all-day event and a known timed event display on the intended dates.
    • Changes persist through the application's intended save/navigation/refetch flow.
    • Custom forms have labels, keyboard dismissal, and appropriate focus management.